@hyperdrive.bot/paseo-server 0.2.6

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

@@ -0,0 +1,4606 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import { promises } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { mapClaudeCanceledToolCall, mapClaudeCompletedToolCall, mapClaudeFailedToolCall, mapClaudeRunningToolCall, } from "./tool-call-mapper.js";
+import { mapTaskNotificationSystemRecordToToolCall, mapTaskNotificationUserContentToToolCall, } from "./task-notification-tool-call.js";
+import { findClaudeModel, getClaudeModelsWithSettings, normalizeClaudeRuntimeModelId, } from "./models.js";
+import { CLAUDE_ULTRACODE_THINKING_OPTION_ID } from "./model-manifest.js";
+import { parsePartialJsonObject } from "./partial-json.js";
+import { resolveTranscriptPath, findTranscriptAcrossProjects } from "./transport/claude-paths.js";
+import { ClaudeSidechainTracker } from "./sidechain-tracker.js";
+import { ClaudeBackgroundTaskTracker } from "./background-task-tracker.js";
+import { buildBackgroundKillPresses } from "./background-shell-kill-keys.js";
+import { extractTaskNotificationLifecycleFromSystemRecord, extractTaskNotificationLifecycleFromUserContent, } from "./task-notification-tool-call.js";
+import { buildClaudeFeatures, claudeModelSupportsFastMode } from "./feature-definitions.js";
+import { buildBinaryDiagnosticRows, buildCommandResolutionDiagnosticRows, formatProviderDiagnostic, formatProviderDiagnosticError, } from "../diagnostic-utils.js";
+import { appendOrReplaceGrowingAssistantMessage, runProviderTurn } from "../provider-runner.js";
+import { renderPromptAttachmentAsText } from "../../prompt-attachments.js";
+import { compressImageForApi } from "./image-compression.js";
+import { realClaudeRewindSdk, revertClaudeConversation, revertClaudeFiles } from "./rewind.js";
+import { normalizeProviderReplayTimestamp } from "../../provider-history-timestamps.js";
+import { composeSystemPromptParts } from "../../system-prompt.js";
+import { SdkTransport } from "./transport/sdk.js";
+import { PtyTransport } from "./transport/pty.js";
+import { createPtySession } from "./pty-session-launcher.js";
+import { trackTransportSpawned } from "../../../monitoring/telemetry.js";
+import { isProviderImageMarkdown, materializeProviderImage, renderProviderImageOutputAsAssistantMarkdown, } from "../provider-image-output.js";
+import { getAgentStreamEventTurnId, } from "../../agent-sdk-types.js";
+import { importSessionFromPersistence } from "../../provider-session-import.js";
+import { SETTING_APPLIES_NEXT_TURN_NOTICE } from "../../provider-notices.js";
+import { checkProviderLaunchAvailable, createProviderEnv, createProviderEnvSpec, resolveProviderLaunch, } from "../../provider-launch-config.js";
+import { isNodePtyAvailable, NODE_PTY_UNAVAILABLE_REASON, resolveClaudeTransport, } from "../../provider-registry.js";
+import { isCommandAvailable } from "../../../../executable-resolution/executable-resolution.js";
+import { withTimeout } from "../../../../utils/promise-timeout.js";
+import { terminateWithTreeKill } from "../../../../utils/tree-kill.js";
+import { execCommand } from "../../../../utils/spawn.js";
+const fsPromises = promises;
+const CLAUDE_SETTING_SOURCES = [
+    "user",
+    "project",
+    "local",
+];
+function readNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+export function normalizeClaudeAskUserQuestionRequestInput(toolName, input) {
+    if (toolName !== "AskUserQuestion" || !Array.isArray(input.questions)) {
+        return input;
+    }
+    // Claude Code's AskUserQuestion schema says "Other" is host-provided, not a
+    // model-supplied option. Paseo's shared question UI uses allowOther for that
+    // freeform answer path.
+    return {
+        ...input,
+        questions: input.questions.map((item) => {
+            if (!isMetadata(item)) {
+                return item;
+            }
+            return {
+                ...item,
+                allowOther: true,
+            };
+        }),
+    };
+}
+function stripClaudeAskUserQuestionUiMetadata(input) {
+    if (!Array.isArray(input.questions)) {
+        return input;
+    }
+    return {
+        ...input,
+        questions: input.questions.map((item) => {
+            if (!isMetadata(item) || !("allowOther" in item)) {
+                return item;
+            }
+            const itemForClaude = { ...item };
+            delete itemForClaude.allowOther;
+            return itemForClaude;
+        }),
+    };
+}
+export function normalizeClaudeAskUserQuestionUpdatedInput(updatedInput, fallbackInput) {
+    const fallback = isMetadata(fallbackInput) ? fallbackInput : {};
+    const base = isMetadata(updatedInput) ? updatedInput : {};
+    // Paseo's shared question UI serializes answers by question header, but Claude's
+    // AskUserQuestion tool expects answer keys to match the full question text. Merge
+    // the original request payload back in so provider callbacks that only return
+    // `{ answers }` still satisfy Claude's full tool input schema.
+    const merged = stripClaudeAskUserQuestionUiMetadata({ ...fallback, ...base });
+    const questions = (Array.isArray(base.questions) ? base.questions : null) ??
+        (Array.isArray(fallback.questions) ? fallback.questions : null);
+    const answers = isMetadata(base.answers) ? base.answers : null;
+    if (!questions || !answers) {
+        return merged;
+    }
+    const normalizedAnswers = {};
+    for (const item of questions) {
+        const question = isMetadata(item) ? item : null;
+        if (!question) {
+            continue;
+        }
+        const questionText = readNonEmptyString(question.question);
+        if (!questionText) {
+            continue;
+        }
+        const header = readNonEmptyString(question.header);
+        const answer = readNonEmptyString(answers[questionText]) ??
+            (header ? readNonEmptyString(answers[header]) : null);
+        if (answer) {
+            normalizedAnswers[questionText] = answer;
+        }
+    }
+    if (Object.keys(normalizedAnswers).length === 0) {
+        return merged;
+    }
+    return {
+        ...merged,
+        answers: normalizedAnswers,
+    };
+}
+function isObjectRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function toObjectRecord(value) {
+    return isObjectRecord(value) ? value : undefined;
+}
+function isUnknownArray(value) {
+    return Array.isArray(value);
+}
+function isImageMimeType(value) {
+    return (value === "image/jpeg" ||
+        value === "image/png" ||
+        value === "image/gif" ||
+        value === "image/webp");
+}
+// Anthropic enforces a 32MB cap on a single API request body. A long session that reads
+// many images (e.g. iterating video frames) accumulates base64 image blocks in the SDK's
+// conversation history and eventually breaches the cap mid-turn with a cryptic upstream
+// error. We compress on input and track cumulative bytes so we either stay well under
+// the cap or fail fast with a clean message before the SDK does.
+const CUMULATIVE_IMAGE_WARN_BYTES = 25 * 1024 * 1024;
+const CUMULATIVE_IMAGE_LIMIT_BYTES = 30 * 1024 * 1024;
+// Stub: rewind plumbing is dormant after the PTY migration. The SDK transport
+// used to expose a `--version` resolver here; the PTY transport reads version
+// via `claude --version` at spawn time and caches it on the session. Returning
+// undefined makes the version telemetry log "unknown" until the PTY-flavored
+// rewind/version resolver is wired up. Tracked in docs/tech-debt.md.
+async function resolveClaudeVersion(_runtimeSettings) {
+    return undefined;
+}
+const CLAUDE_CAPABILITIES = {
+    supportsStreaming: true,
+    supportsSessionPersistence: true,
+    supportsSessionListing: true,
+    supportsDynamicModes: true,
+    supportsMcpServers: true,
+    supportsReasoningStream: true,
+    supportsToolInvocations: true,
+    supportsRewindConversation: true,
+    supportsRewindFiles: true,
+    supportsRewindBoth: true,
+};
+const DEFAULT_MODES = [
+    {
+        id: "default",
+        label: "Always Ask",
+        description: "Prompts for permission the first time a tool is used",
+    },
+    {
+        id: "auto",
+        label: "Auto mode",
+        description: "Uses a model classifier to review permission prompts automatically",
+    },
+    {
+        id: "acceptEdits",
+        label: "Accept File Edits",
+        description: "Automatically approves edit-focused tools without prompting",
+    },
+    {
+        id: "plan",
+        label: "Plan Mode",
+        description: "Analyze the codebase without executing tools or edits",
+    },
+    {
+        id: "bypassPermissions",
+        label: "Bypass",
+        description: "Skip all permission prompts (use with caution)",
+    },
+];
+const VALID_CLAUDE_MODES = new Set(DEFAULT_MODES.map((mode) => mode.id));
+const REWIND_COMMAND_NAME = "rewind";
+const REWIND_COMMAND = {
+    name: REWIND_COMMAND_NAME,
+    description: "Rewind tracked files to a previous user message",
+    argumentHint: "[user_message_uuid]",
+};
+const CLAUDE_ROOT_ONLY_COMMANDS = new Set([
+    "clear",
+    "compact",
+    "context",
+    "debug",
+    "extra-usage",
+    "heapdump",
+    "init",
+    "loop",
+    "schedule",
+    "usage",
+]);
+const INTERRUPT_TOOL_USE_PLACEHOLDER = "[Request interrupted by user for tool use]";
+const INTERRUPT_PLACEHOLDER_PATTERN = /^\[Request interrupted by user(?:[^\]]*)\]$/;
+const NO_RESPONSE_REQUESTED_PLACEHOLDER = "No response requested.";
+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 classifyClaudeSlashCommand(commandName) {
+    // Claude exposes commands and skills as one flat SDK list, without structured source
+    // metadata. Keep obvious root-only/session controls out of inline autocomplete and
+    // treat the rest as skills; the worst failure mode is an inert inline suggestion.
+    return CLAUDE_ROOT_ONLY_COMMANDS.has(commandName) ? "command" : "skill";
+}
+function resolvePathEnvKey() {
+    if (process.env["Path"] !== undefined)
+        return "Path";
+    if (process.env["PATH"] !== undefined)
+        return "PATH";
+    return null;
+}
+function errorToMessageString(error) {
+    if (typeof error === "string")
+        return error;
+    if (error instanceof Error)
+        return error.message;
+    return "";
+}
+function firstStringField(input, primaryKey, secondaryKey) {
+    const primary = input[primaryKey];
+    if (typeof primary === "string")
+        return primary;
+    const secondary = input[secondaryKey];
+    if (typeof secondary === "string")
+        return secondary;
+    return undefined;
+}
+function extractSessionIdRaw(msg) {
+    if (typeof msg.session_id === "string")
+        return msg.session_id;
+    if (typeof msg.sessionId === "string")
+        return msg.sessionId;
+    if (typeof msg.session?.id === "string")
+        return msg.session.id;
+    return "";
+}
+function isClaudeThinkingEffort(value) {
+    return (value === "low" ||
+        value === "medium" ||
+        value === "high" ||
+        value === "xhigh" ||
+        value === "max");
+}
+function isClaudeThinkingOption(value) {
+    return value === CLAUDE_ULTRACODE_THINKING_OPTION_ID || isClaudeThinkingEffort(value);
+}
+const MAX_RECENT_STDERR_CHARS = 4000;
+const STDERR_FLUSH_WAIT_MS = 150;
+const STDERR_FLUSH_POLL_INTERVAL_MS = 10;
+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 = toObjectRecord(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",
+        pathToClaudeCodeExecutable: typeof options.pathToClaudeCodeExecutable === "string"
+            ? options.pathToClaudeCodeExecutable
+            : null,
+        persistSession: typeof options.persistSession === "boolean" ? options.persistSession : null,
+        fastMode: readClaudeFastModeSetting(options.settings),
+    };
+}
+function readClaudeFastModeSetting(settings) {
+    if (!settings || typeof settings === "string") {
+        return null;
+    }
+    return typeof settings.fastMode === "boolean" ? settings.fastMode : null;
+}
+function mergeClaudeSettings(settings, updates) {
+    if (!settings || typeof settings === "string") {
+        return settings ?? updates;
+    }
+    return { ...settings, ...updates };
+}
+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 = toObjectRecord(value);
+        if (!record) {
+            seen.delete(objectValue);
+            return "[invalid]";
+        }
+        const normalized = {};
+        for (const key of Object.keys(record).sort()) {
+            normalized[key] = normalizeForDeterministicString(record[key], seen);
+        }
+        seen.delete(objectValue);
+        return normalized;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return "[unsupported]";
+}
+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 {
+        if (typeof value === "string") {
+            return value;
+        }
+        if (typeof value === "number" || typeof value === "boolean") {
+            return String(value);
+        }
+        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);
+}
+function toBase64ImageOutput(block) {
+    const record = toObjectRecord(block);
+    if (!record || record.type !== "image") {
+        return null;
+    }
+    const source = toObjectRecord(record.source);
+    if (!source || source.type !== "base64" || typeof source.data !== "string") {
+        return null;
+    }
+    return {
+        data: source.data,
+        mimeType: typeof source.media_type === "string" ? source.media_type : null,
+    };
+}
+// Claude returns images inside tool_result content as base64 Anthropic blocks. Left in place they
+// reach coerceToolResultContentToString, which JSON.stringifies the whole array — dumping base64
+// into the tool output. We pull those blocks out to render them as image markdown and leave a
+// "[image]" placeholder so image-only results still produce non-empty output.
+function splitClaudeToolResultImages(content) {
+    if (!Array.isArray(content)) {
+        return { images: [], text: content };
+    }
+    const images = [];
+    const text = content.map((block) => {
+        const image = toBase64ImageOutput(block);
+        if (image) {
+            images.push(image);
+            return { type: "text", text: "[image]" };
+        }
+        return block;
+    });
+    return { images, text };
+}
+function normalizeClaudeTranscriptText(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : null;
+}
+function isClaudeInterruptPlaceholderText(value) {
+    const normalized = normalizeClaudeTranscriptText(value);
+    return normalized !== null && INTERRUPT_PLACEHOLDER_PATTERN.test(normalized);
+}
+function isClaudeNoResponsePlaceholderText(value) {
+    return normalizeClaudeTranscriptText(value) === NO_RESPONSE_REQUESTED_PLACEHOLDER;
+}
+const LOCAL_COMMAND_STDOUT_PATTERN = /^\s*<local-command-stdout>[\s\S]*<\/local-command-stdout>\s*$/;
+const CLAUDE_COMMAND_MESSAGE_PATTERN = /<command-message>([\s\S]*?)<\/command-message>/;
+const CLAUDE_COMMAND_ARGS_PATTERN = /<command-args>([\s\S]*?)<\/command-args>/;
+const CLAUDE_COMMAND_NAME_PATTERN = /<command-name>([\s\S]*?)<\/command-name>/;
+function isClaudeLocalCommandStdout(value) {
+    const normalized = normalizeClaudeTranscriptText(value);
+    return normalized !== null && LOCAL_COMMAND_STDOUT_PATTERN.test(normalized);
+}
+function isClaudeTranscriptNoiseText(value) {
+    return (isClaudeInterruptPlaceholderText(value) ||
+        isClaudeNoResponsePlaceholderText(value) ||
+        isClaudeLocalCommandStdout(value));
+}
+function collectClaudeTextContentParts(content) {
+    if (typeof content === "string") {
+        const normalized = normalizeClaudeTranscriptText(content);
+        return normalized ? [normalized] : [];
+    }
+    if (!isUnknownArray(content)) {
+        return [];
+    }
+    const parts = [];
+    for (const block of content) {
+        const blockRecord = toObjectRecord(block);
+        if (!blockRecord) {
+            continue;
+        }
+        const text = normalizeClaudeTranscriptText(blockRecord.text);
+        if (text) {
+            parts.push(text);
+            continue;
+        }
+        const input = normalizeClaudeTranscriptText(blockRecord.input);
+        if (input) {
+            parts.push(input);
+        }
+    }
+    return parts;
+}
+function isClaudeTranscriptNoiseContent(content) {
+    const parts = collectClaudeTextContentParts(content);
+    return parts.length > 0 && parts.every((part) => isClaudeTranscriptNoiseText(part));
+}
+export function extractUserMessageText(content) {
+    if (typeof content === "string") {
+        const normalized = content.trim();
+        if (!normalized || isClaudeTranscriptNoiseText(normalized)) {
+            return null;
+        }
+        return normalizeClaudeUserPromptText(normalized);
+    }
+    if (!Array.isArray(content)) {
+        return null;
+    }
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object") {
+            continue;
+        }
+        const text = typeof block.text === "string" ? block.text : undefined;
+        if (text && text.trim()) {
+            const trimmed = text.trim();
+            if (!isClaudeTranscriptNoiseText(trimmed)) {
+                const normalized = normalizeClaudeUserPromptText(trimmed);
+                if (normalized) {
+                    parts.push(normalized);
+                }
+            }
+            continue;
+        }
+        const input = typeof block.input === "string" ? block.input : undefined;
+        if (input && input.trim()) {
+            const trimmed = input.trim();
+            if (!isClaudeTranscriptNoiseText(trimmed)) {
+                const normalized = normalizeClaudeUserPromptText(trimmed);
+                if (normalized) {
+                    parts.push(normalized);
+                }
+            }
+        }
+    }
+    if (parts.length === 0) {
+        return null;
+    }
+    const combined = parts.join("\n\n").trim();
+    return combined.length > 0 ? combined : null;
+}
+function isMetadata(value) {
+    return typeof value === "object" && value !== null;
+}
+function createDefaultToolUseCacheEntry(id, block) {
+    const nameFromBlock = typeof block.name === "string" && block.name.length > 0 ? block.name : "tool";
+    let server;
+    if (typeof block.server === "string" && block.server.length > 0) {
+        server = block.server;
+    }
+    else if (typeof block.name === "string" && block.name.length > 0) {
+        server = block.name;
+    }
+    else {
+        server = "tool";
+    }
+    return {
+        id,
+        name: nameFromBlock,
+        server,
+        classification: "generic",
+        started: false,
+    };
+}
+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;
+    }
+    const type = value.type;
+    if (type === "stdio") {
+        return typeof value.command === "string";
+    }
+    if (type === "http" || type === "sse") {
+        return typeof value.url === "string";
+    }
+    return false;
+}
+function isMcpServersRecord(value) {
+    if (!isMetadata(value)) {
+        return false;
+    }
+    for (const config of Object.values(value)) {
+        if (!isMcpServerConfig(config)) {
+            return false;
+        }
+    }
+    return true;
+}
+function isPermissionMode(value) {
+    return typeof value === "string" && VALID_CLAUDE_MODES.has(value);
+}
+function isTruthyEnvValue(value) {
+    const normalized = value?.trim().toLowerCase();
+    return (normalized !== undefined &&
+        normalized.length > 0 &&
+        normalized !== "0" &&
+        normalized !== "false" &&
+        normalized !== "no" &&
+        normalized !== "off");
+}
+function detectIneligibleAutoModeTransport(env) {
+    if (isTruthyEnvValue(env.CLAUDE_CODE_USE_BEDROCK)) {
+        return "Bedrock";
+    }
+    if (isTruthyEnvValue(env.CLAUDE_CODE_USE_VERTEX)) {
+        return "Vertex";
+    }
+    return null;
+}
+function assertClaudeAutoModeEligible(mode, env) {
+    if (mode !== "auto") {
+        return;
+    }
+    const transport = detectIneligibleAutoModeTransport(env);
+    if (transport === null) {
+        return;
+    }
+    throw new Error(`Claude Auto mode requires the Anthropic API and is not supported when Claude Code uses ${transport}. Select another permission mode or unset the ${transport === "Bedrock" ? "CLAUDE_CODE_USE_BEDROCK" : "CLAUDE_CODE_USE_VERTEX"} environment variable.`);
+}
+function coerceSessionMetadata(metadata) {
+    if (!isMetadata(metadata)) {
+        return {};
+    }
+    const result = {};
+    if (metadata.provider === "claude" || metadata.provider === "codex") {
+        result.provider = metadata.provider;
+    }
+    if (typeof metadata.cwd === "string") {
+        result.cwd = metadata.cwd;
+    }
+    if (typeof metadata.modeId === "string") {
+        result.modeId = metadata.modeId;
+    }
+    if (typeof metadata.model === "string") {
+        result.model = metadata.model;
+    }
+    if (typeof metadata.title === "string" || metadata.title === null) {
+        result.title = metadata.title;
+    }
+    if (typeof metadata.approvalPolicy === "string") {
+        result.approvalPolicy = metadata.approvalPolicy;
+    }
+    if (typeof metadata.sandboxMode === "string") {
+        result.sandboxMode = metadata.sandboxMode;
+    }
+    if (typeof metadata.networkAccess === "boolean") {
+        result.networkAccess = metadata.networkAccess;
+    }
+    if (typeof metadata.webSearch === "boolean") {
+        result.webSearch = metadata.webSearch;
+    }
+    if (isMetadata(metadata.extra)) {
+        const extra = {};
+        if (isMetadata(metadata.extra.codex)) {
+            extra.codex = metadata.extra.codex;
+        }
+        if (isClaudeExtra(metadata.extra.claude)) {
+            extra.claude = metadata.extra.claude;
+        }
+        if (extra.codex || extra.claude) {
+            result.extra = extra;
+        }
+    }
+    if (typeof metadata.systemPrompt === "string") {
+        result.systemPrompt = metadata.systemPrompt;
+    }
+    if (isMcpServersRecord(metadata.mcpServers)) {
+        result.mcpServers = metadata.mcpServers;
+    }
+    return result;
+}
+export function toClaudeSdkMcpConfig(config) {
+    switch (config.type) {
+        case "stdio":
+            return {
+                type: "stdio",
+                command: config.command,
+                args: config.args,
+                env: config.env,
+                alwaysLoad: config.alwaysLoad,
+            };
+        case "http":
+            return {
+                type: "http",
+                url: config.url,
+                headers: config.headers,
+                alwaysLoad: config.alwaysLoad,
+            };
+        case "sse":
+            return {
+                type: "sse",
+                url: config.url,
+                headers: config.headers,
+                alwaysLoad: config.alwaysLoad,
+            };
+    }
+    throw new Error("Unhandled MCP server config type");
+}
+function isClaudeContentChunk(value) {
+    return isMetadata(value) && typeof value.type === "string";
+}
+function isClaudeExtra(value) {
+    return isMetadata(value);
+}
+function isPermissionUpdate(value) {
+    if (!isMetadata(value)) {
+        return false;
+    }
+    const type = value.type;
+    if (type !== "addRules" && type !== "replaceRules" && type !== "removeRules") {
+        return false;
+    }
+    const rules = value.rules;
+    const behavior = value.behavior;
+    const destination = value.destination;
+    return Array.isArray(rules) && typeof behavior === "string" && typeof destination === "string";
+}
+function resolvePermissionKind(toolName, input) {
+    if (toolName === "ExitPlanMode")
+        return "plan";
+    if (toolName === "AskUserQuestion" && Array.isArray(input.questions)) {
+        return "question";
+    }
+    return "tool";
+}
+function getClaudeModeLabel(modeId) {
+    return DEFAULT_MODES.find((mode) => mode.id === modeId)?.label ?? modeId;
+}
+function buildClaudePlanPermissionActions(resumeMode) {
+    const actions = [
+        {
+            id: "reject",
+            label: "Reject",
+            behavior: "deny",
+            variant: "danger",
+            intent: "dismiss",
+        },
+        {
+            id: "implement",
+            label: "Implement",
+            behavior: "allow",
+            variant: "primary",
+            intent: "implement",
+        },
+    ];
+    if (resumeMode === "bypassPermissions") {
+        actions.push({
+            id: "implement_resume",
+            label: `Implement with ${getClaudeModeLabel(resumeMode)}`,
+            behavior: "allow",
+            variant: "secondary",
+            intent: "implement_resume",
+        });
+    }
+    return actions;
+}
+class TimelineAssembler {
+    constructor() {
+        this.messages = new Map();
+        this.finalizedMessageIds = new Set();
+        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 [];
+        }
+        if (this.finalizedMessageIds.has(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 = toObjectRecord(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);
+        }
+        this.finalizedMessageIds.add(messageId);
+        this.messages.delete(messageId);
+        return items;
+    }
+    emitNewContent(state) {
+        const items = [];
+        const nextAssistantText = state.assistantText.slice(state.emittedAssistantLength);
+        if (nextAssistantText.length > 0 &&
+            nextAssistantText !== INTERRUPT_TOOL_USE_PLACEHOLDER &&
+            !isClaudeTranscriptNoiseText(nextAssistantText)) {
+            state.emittedAssistantLength = state.assistantText.length;
+            items.push({ type: "assistant_message", text: nextAssistantText, messageId: state.id });
+        }
+        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 = toObjectRecord(message);
+        const messageContainer = toObjectRecord(candidate?.message);
+        return (readTrimmedString(candidate?.message_id) ?? readTrimmedString(messageContainer?.id) ?? null);
+    }
+    readMessageIdFromStreamEvent(event) {
+        const messageContainer = toObjectRecord(event.message);
+        return readTrimmedString(event.message_id) ?? readTrimmedString(messageContainer?.id) ?? null;
+    }
+}
+function isSyntheticUserEntry(entry) {
+    const candidate = toObjectRecord(entry);
+    if (!candidate) {
+        return false;
+    }
+    return (candidate.isSynthetic === true || candidate.isMeta === true || Boolean(candidate.toolUseResult));
+}
+function isToolResultUserEntry(entry) {
+    const candidate = toObjectRecord(entry);
+    if (!candidate) {
+        return false;
+    }
+    const message = toObjectRecord(candidate.message);
+    const content = message?.content;
+    return (Array.isArray(content) && content.some((block) => toObjectRecord(block)?.type === "tool_result"));
+}
+function isSyntheticHistoryUserEntry(entry) {
+    return isSyntheticUserEntry(entry) && !isToolResultUserEntry(entry);
+}
+function firstTrimmedString(sources) {
+    for (const source of sources) {
+        const value = readTrimmedString(source);
+        if (value) {
+            return value;
+        }
+    }
+    return null;
+}
+function readTranscriptUuid(message) {
+    const root = toObjectRecord(message) ?? {};
+    const messageType = readTrimmedString(root.type);
+    if (messageType !== "user" && messageType !== "assistant") {
+        return null;
+    }
+    return firstTrimmedString([root.uuid]);
+}
+export function readEventIdentifiers(message) {
+    const root = toObjectRecord(message) ?? {};
+    const messageType = readTrimmedString(root.type);
+    const streamEvent = toObjectRecord(root.event);
+    const streamEventMessage = toObjectRecord(streamEvent?.message);
+    const messageContainer = toObjectRecord(root.message);
+    const messageIdFromUuid = messageType === "user" || messageType === "assistant" || messageType === "system"
+        ? root.uuid
+        : undefined;
+    return {
+        taskId: firstTrimmedString([
+            root.task_id,
+            streamEvent?.task_id,
+            streamEventMessage?.task_id,
+            messageContainer?.task_id,
+        ]),
+        parentMessageId: firstTrimmedString([
+            root.parent_message_id,
+            streamEvent?.parent_message_id,
+            streamEventMessage?.parent_message_id,
+            messageContainer?.parent_message_id,
+        ]),
+        messageId: firstTrimmedString([
+            root.message_id,
+            streamEvent?.message_id,
+            streamEventMessage?.id,
+            streamEventMessage?.message_id,
+            messageContainer?.id,
+            messageContainer?.message_id,
+            messageIdFromUuid,
+        ]),
+    };
+}
+export class ClaudeAgentClient {
+    constructor(options) {
+        this.provider = "claude";
+        this.capabilities = CLAUDE_CAPABILITIES;
+        this.defaults = options.defaults;
+        this.logger = options.logger.child({ module: "agent", provider: "claude" });
+        this.runtimeSettings = options.runtimeSettings;
+        this.queryFactory = options.queryFactory;
+        this.resolveBinary = options.resolveBinary ?? (() => resolveClaudeBinary(this.runtimeSettings));
+        this.configDir = options.configDir;
+    }
+    async createSession(config, launchContext, options) {
+        const claudeConfig = this.assertConfig(config);
+        return new ClaudeAgentSession(claudeConfig, {
+            defaults: this.defaults,
+            runtimeSettings: this.runtimeSettings,
+            agentId: launchContext?.agentId,
+            launchEnv: launchContext?.env,
+            persistSession: options?.persistSession,
+            logger: this.logger,
+            queryFactory: this.queryFactory,
+            resolveBinary: this.resolveBinary,
+            // Story 3.6 — Fork-resume: seed claudeSessionId without a persistence
+            // handle so the SDK/PTY paths emit `--resume <sid>`, but no read/write
+            // is performed against the source JSONL by paseo itself. Claude CLI
+            // forks the conversation into a new SID; source remains byte-identical.
+            ...(options?.resumeSessionId ? { resumeSessionId: options.resumeSessionId } : {}),
+        });
+    }
+    async resumeSession(handle, overrides, launchContext) {
+        const metadata = coerceSessionMetadata(handle.metadata);
+        const merged = { ...metadata, ...overrides };
+        if (!merged.cwd) {
+            throw new Error("Claude resume requires the original working directory in metadata");
+        }
+        const mergedConfig = {
+            ...merged,
+            provider: "claude",
+            cwd: merged.cwd,
+        };
+        const claudeConfig = this.assertConfig(mergedConfig);
+        return new ClaudeAgentSession(claudeConfig, {
+            defaults: this.defaults,
+            runtimeSettings: this.runtimeSettings,
+            handle,
+            agentId: launchContext?.agentId,
+            launchEnv: launchContext?.env,
+            logger: this.logger,
+            queryFactory: this.queryFactory,
+            resolveBinary: this.resolveBinary,
+        });
+    }
+    async fetchCatalog(_options) {
+        // Claude exposes a global catalog here; cwd/force are intentionally irrelevant.
+        const models = await getClaudeModelsWithSettings(this.logger, this.configDir);
+        return { models, modes: DEFAULT_MODES };
+    }
+    async listFeatures(config) {
+        const claudeConfig = this.assertConfig(config);
+        return buildClaudeFeatures({
+            modelId: claudeConfig.model,
+            fastModeEnabled: claudeConfig.featureValues?.fast_mode === true,
+        });
+    }
+    async listImportableSessions(options) {
+        const configDir = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
+        const projectsRoot = path.join(configDir, "projects");
+        if (!(await pathExists(projectsRoot))) {
+            return [];
+        }
+        const limit = options?.limit ?? 20;
+        const candidates = await collectRecentClaudeSessions(projectsRoot, limit * 3);
+        const parsed = await Promise.all(candidates.map((candidate) => parseClaudeSessionDescriptor(candidate.path, candidate.mtime)));
+        return parsed
+            .filter((session) => session !== null)
+            .slice(0, limit);
+    }
+    async importSession(input, context) {
+        return importSessionFromPersistence({
+            provider: "claude",
+            request: input,
+            context,
+            resumeSession: this.resumeSession.bind(this),
+        });
+    }
+    async isAvailable() {
+        // Story 4.1 — When transport is explicitly "pty", the daemon needs node-pty
+        // loadable. Short-circuit unavailable with a reason exposed via diagnostic.
+        if (this.runtimeSettings?.transport === "pty" && !isNodePtyAvailable()) {
+            return false;
+        }
+        const command = this.runtimeSettings?.command;
+        if (command?.mode === "replace") {
+            return await isCommandAvailable(command.argv[0]);
+        }
+        return await isCommandAvailable("claude");
+    }
+    /**
+     * Story 4.1 — Detailed availability with rebuild diagnostic. The public
+     * `isAvailable()` keeps its Promise<boolean> contract (AgentClient interface);
+     * tests and `getDiagnostic()` consume this for the rebuild hint.
+     */
+    async checkAvailability() {
+        if (this.runtimeSettings?.transport === "pty" && !isNodePtyAvailable()) {
+            return { available: false, reason: NODE_PTY_UNAVAILABLE_REASON };
+        }
+        return { available: await this.isAvailable() };
+    }
+    async getDiagnostic() {
+        try {
+            const launch = await resolveProviderLaunch({
+                commandConfig: this.runtimeSettings?.command,
+                defaultBinary: "claude",
+            });
+            const availability = await checkProviderLaunchAvailable(launch);
+            const auth = availability.available
+                ? await resolveClaudeAuth(launch, availability, this.runtimeSettings)
+                : null;
+            return {
+                diagnostic: formatProviderDiagnostic("Claude Code", [
+                    ...(await buildCommandResolutionDiagnosticRows(launch, {
+                        knownBinaryNames: ["claude"],
+                    })),
+                    ...(await buildBinaryDiagnosticRows(launch, availability)),
+                    ...(auth ? [{ label: "Auth", value: auth }] : []),
+                ]),
+            };
+        }
+        catch (error) {
+            return {
+                diagnostic: formatProviderDiagnosticError("Claude Code", error),
+            };
+        }
+    }
+    assertConfig(config) {
+        if (config.provider !== "claude") {
+            throw new Error(`ClaudeAgentClient received config for provider '${config.provider}'`);
+        }
+        return { ...config, provider: "claude" };
+    }
+}
+async function resolveClaudeBinary(runtimeSettings) {
+    const launch = await resolveProviderLaunch({
+        commandConfig: runtimeSettings?.command,
+        defaultBinary: "claude",
+    });
+    const availability = await checkProviderLaunchAvailable(launch);
+    if (availability.available) {
+        return availability.resolvedPath ?? launch.command;
+    }
+    throw new Error("Claude binary not found. Install Claude Code (https://github.com/anthropics/claude-code) and ensure it is available in your shell PATH.");
+}
+async function resolveClaudeAuth(launch, availability, runtimeSettings) {
+    const run = async (executable, args) => {
+        try {
+            return await execCommand(executable, args, {
+                ...createProviderEnvSpec({ runtimeSettings }),
+                timeout: 5000,
+            });
+        }
+        catch (error) {
+            const err = toObjectRecord(error);
+            const stdout = typeof err?.stdout === "string" ? err.stdout : "";
+            const stderr = typeof err?.stderr === "string" ? err.stderr : "";
+            const fallbackMessage = typeof err?.message === "string" ? err.message : "";
+            return { stdout, stderr: stderr || fallbackMessage };
+        }
+    };
+    try {
+        const executable = availability.resolvedPath ?? launch.command;
+        const result = await run(executable, [...launch.args, "auth", "status"]);
+        const combined = [result.stdout, result.stderr]
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0)
+            .join("\n");
+        return combined || null;
+    }
+    catch {
+        return null;
+    }
+}
+function extractContextWindowSize(modelUsage) {
+    const usageRecord = toObjectRecord(modelUsage);
+    if (!usageRecord) {
+        return undefined;
+    }
+    let maxContextWindow;
+    for (const value of Object.values(usageRecord)) {
+        const valueRecord = toObjectRecord(value);
+        if (!valueRecord) {
+            continue;
+        }
+        const contextWindow = valueRecord.contextWindow;
+        if (typeof contextWindow !== "number" ||
+            !Number.isFinite(contextWindow) ||
+            contextWindow <= 0) {
+            continue;
+        }
+        maxContextWindow = Math.max(maxContextWindow ?? 0, contextWindow);
+    }
+    return maxContextWindow;
+}
+function readStreamRequestInputTokens(event) {
+    const messageUsage = toObjectRecord(toObjectRecord(event.message)?.usage);
+    if (!messageUsage) {
+        return undefined;
+    }
+    const usage = messageUsage;
+    const inputTokens = typeof usage.input_tokens === "number" && Number.isFinite(usage.input_tokens)
+        ? usage.input_tokens
+        : undefined;
+    const cacheCreationInputTokens = typeof usage.cache_creation_input_tokens === "number" &&
+        Number.isFinite(usage.cache_creation_input_tokens)
+        ? usage.cache_creation_input_tokens
+        : 0;
+    const cacheReadInputTokens = typeof usage.cache_read_input_tokens === "number" &&
+        Number.isFinite(usage.cache_read_input_tokens)
+        ? usage.cache_read_input_tokens
+        : 0;
+    if (typeof inputTokens !== "number" || inputTokens < 0) {
+        return undefined;
+    }
+    return inputTokens + cacheCreationInputTokens + cacheReadInputTokens;
+}
+function readStreamRequestOutputTokens(event) {
+    const outputTokens = toObjectRecord(event.usage)?.output_tokens;
+    if (typeof outputTokens !== "number" || !Number.isFinite(outputTokens) || outputTokens < 0) {
+        return undefined;
+    }
+    return outputTokens;
+}
+function readLastUsageIteration(usage) {
+    const iterations = toObjectRecord(usage)?.iterations;
+    if (!Array.isArray(iterations)) {
+        return undefined;
+    }
+    for (let index = iterations.length - 1; index >= 0; index -= 1) {
+        const candidate = toObjectRecord(iterations[index]);
+        if (candidate) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function readUsageTokenTotal(usage) {
+    const usageWithCacheCreation = usage;
+    const inputTokens = typeof usage.input_tokens === "number" && Number.isFinite(usage.input_tokens)
+        ? usage.input_tokens
+        : 0;
+    const cacheCreationInputTokens = typeof usageWithCacheCreation.cache_creation_input_tokens === "number" &&
+        Number.isFinite(usageWithCacheCreation.cache_creation_input_tokens)
+        ? usageWithCacheCreation.cache_creation_input_tokens
+        : 0;
+    const cacheReadInputTokens = typeof usage.cache_read_input_tokens === "number" &&
+        Number.isFinite(usage.cache_read_input_tokens)
+        ? usage.cache_read_input_tokens
+        : 0;
+    const outputTokens = typeof usage.output_tokens === "number" && Number.isFinite(usage.output_tokens)
+        ? usage.output_tokens
+        : 0;
+    const total = inputTokens + cacheCreationInputTokens + cacheReadInputTokens + outputTokens;
+    return total > 0 ? total : undefined;
+}
+function readActiveUsageTokens(usage) {
+    const activeUsage = readLastUsageIteration(usage);
+    return activeUsage ? readUsageTokenTotal(activeUsage) : undefined;
+}
+function readLegacyResultUsageTokens(usage) {
+    const usageRecord = toObjectRecord(usage);
+    return usageRecord ? readUsageTokenTotal(usageRecord) : undefined;
+}
+function isClaudeSubagentToolName(name) {
+    return name === "Task" || name === "Agent";
+}
+function readClaudeParentToolUseId(message) {
+    if (!("parent_tool_use_id" in message)) {
+        return null;
+    }
+    const parentToolUseId = message.parent_tool_use_id;
+    return typeof parentToolUseId === "string" && parentToolUseId.length > 0 ? parentToolUseId : null;
+}
+class ClaudeContextUsageState {
+    constructor(initialContextWindowMaxTokens) {
+        this.completedResultTurns = 0;
+        this.contextWindowMaxTokens = initialContextWindowMaxTokens;
+    }
+    beginTurn() {
+        this.streamRequestInputTokens = undefined;
+        this.streamRequestOutputTokens = undefined;
+        this.compactedContextWindowUsedTokens = undefined;
+    }
+    setInitialContextWindowMaxTokens(contextWindowMaxTokens) {
+        this.contextWindowMaxTokens = contextWindowMaxTokens;
+    }
+    recordModelUsage(modelUsage) {
+        const contextWindowMaxTokens = extractContextWindowSize(modelUsage);
+        if (contextWindowMaxTokens !== undefined) {
+            this.contextWindowMaxTokens = contextWindowMaxTokens;
+        }
+        return this.contextWindowMaxTokens;
+    }
+    buildStreamUsageEvent(event) {
+        const streamEvent = toObjectRecord(event);
+        if (!streamEvent) {
+            return null;
+        }
+        const eventType = readTrimmedString(streamEvent.type);
+        if (eventType === "message_start") {
+            const inputTokens = readStreamRequestInputTokens(streamEvent);
+            if (typeof inputTokens !== "number") {
+                return null;
+            }
+            this.streamRequestInputTokens = inputTokens;
+            this.streamRequestOutputTokens = 0;
+        }
+        else if (eventType === "message_delta") {
+            const outputTokens = readStreamRequestOutputTokens(streamEvent);
+            if (typeof outputTokens !== "number") {
+                return null;
+            }
+            this.streamRequestOutputTokens = outputTokens;
+        }
+        else {
+            return null;
+        }
+        const usedTokens = this.streamUsedTokens();
+        if (usedTokens === undefined) {
+            return null;
+        }
+        return this.createUsageUpdatedEvent(usedTokens);
+    }
+    buildResultUsage(message, modelUsage) {
+        try {
+            if (!message.usage) {
+                return undefined;
+            }
+            const usage = {
+                inputTokens: message.usage.input_tokens,
+                cachedInputTokens: message.usage.cache_read_input_tokens,
+                outputTokens: message.usage.output_tokens,
+                totalCostUsd: message.total_cost_usd,
+            };
+            const modelContextWindowMaxTokens = this.recordModelUsage(modelUsage ?? message.modelUsage);
+            if (this.contextWindowMaxTokens !== undefined) {
+                usage.contextWindowMaxTokens = this.contextWindowMaxTokens;
+            }
+            else if (modelContextWindowMaxTokens !== undefined) {
+                usage.contextWindowMaxTokens = modelContextWindowMaxTokens;
+            }
+            const activeResultUsageTokens = readActiveUsageTokens(message.usage) ??
+                (this.completedResultTurns === 0 ? readLegacyResultUsageTokens(message.usage) : undefined);
+            const usedTokens = this.streamUsedTokens() ?? activeResultUsageTokens ?? this.compactedContextWindowUsedTokens;
+            if (usedTokens !== undefined) {
+                usage.contextWindowUsedTokens = usedTokens;
+            }
+            return usage;
+        }
+        finally {
+            this.compactedContextWindowUsedTokens = undefined;
+            this.completedResultTurns += 1;
+        }
+    }
+    streamUsedTokens() {
+        if (typeof this.streamRequestInputTokens !== "number" ||
+            typeof this.streamRequestOutputTokens !== "number") {
+            return undefined;
+        }
+        const usedTokens = this.streamRequestInputTokens + this.streamRequestOutputTokens;
+        return usedTokens > 0 ? usedTokens : undefined;
+    }
+    createUsageUpdatedEvent(contextWindowUsedTokens) {
+        const usage = {
+            contextWindowUsedTokens,
+        };
+        if (this.contextWindowMaxTokens !== undefined) {
+            usage.contextWindowMaxTokens = this.contextWindowMaxTokens;
+        }
+        return {
+            type: "usage_updated",
+            provider: "claude",
+            usage,
+        };
+    }
+    buildCompactionUsageEvent(postTokens) {
+        this.streamRequestInputTokens = undefined;
+        this.streamRequestOutputTokens = undefined;
+        this.compactedContextWindowUsedTokens = postTokens;
+        const usage = {};
+        if (this.contextWindowMaxTokens !== undefined) {
+            usage.contextWindowMaxTokens = this.contextWindowMaxTokens;
+        }
+        if (postTokens !== undefined) {
+            usage.contextWindowUsedTokens = postTokens;
+        }
+        return {
+            type: "usage_updated",
+            provider: "claude",
+            usage,
+        };
+    }
+}
+export class ClaudeAgentSession {
+    /**
+     * Register a hook event handler for an agent. Stub in Epic 1 — Epic 3 wires
+     * incoming hook events from the PTY transport into this handler.
+     */
+    registerHookHandler(agentId, handler) {
+        this.hookEventHandlers.set(agentId, handler);
+    }
+    unregisterHookHandler(agentId) {
+        this.hookEventHandlers.delete(agentId);
+    }
+    constructor(config, options) {
+        this.provider = "claude";
+        this.capabilities = CLAUDE_CAPABILITIES;
+        this.query = null;
+        this.childProcess = null;
+        this.input = null;
+        this.planResumeMode = null;
+        this.availableModes = DEFAULT_MODES;
+        this.toolUseCache = new Map();
+        this.toolUseIndexToId = new Map();
+        this.toolUseInputBuffers = new Map();
+        this.pendingPermissions = new Map();
+        this.activeForegroundTurnId = null;
+        this.autonomousTurn = null;
+        this.subscribers = new Set();
+        this.timelineAssembler = new TimelineAssembler();
+        this.sidechainTracker = new ClaudeSidechainTracker({
+            getToolInput: (toolUseId) => this.toolUseCache.get(toolUseId)?.input ?? null,
+        });
+        // Tracks Claude Code background shells (`Bash` run_in_background) that outlive
+        // the turn, so the agent keeps surfacing as "Running" until they finish or are
+        // dismissed. Fed from the transport-agnostic message stream (works for PTY).
+        this.backgroundTaskTracker = new ClaudeBackgroundTaskTracker();
+        this.persistedHistory = [];
+        this.historyPending = false;
+        this.turnState = "idle";
+        this.nextTurnOrdinal = 1;
+        this.cancelCurrentTurn = null;
+        this.cachedRuntimeInfo = null;
+        this.lastOptionsModel = null;
+        this.lastRuntimeModel = null;
+        this.compacting = false;
+        this.queryPumpPromise = null;
+        this.queryRestartNeeded = false;
+        // Story 3.3 — transport handle used by setMode/setModel/setThinkingOption to
+        // discriminate between PTY (slash-command) and SDK (query-object) paths.
+        // Populated by ensureQuery() with the live SdkTransport; tests inject a
+        // PtyTransport stub directly.
+        this.activeTransport = null;
+        // Story 4.1 — Resolved transport ("sdk" | "pty"), cached for session lifetime.
+        // Populated lazily by ensureTransport() from runtimeSettings.transport.
+        this.resolvedTransport = null;
+        // Story 4.4 — Cached `claude --version` string, populated lazily in the
+        // background after the first ensureTransport() call. "unknown" if probing
+        // fails or has not yet resolved when telemetry fires.
+        this.claudeVersion = null;
+        this.transportSpawnedTelemetryFired = false;
+        this.pendingInterruptAbort = false;
+        this.foregroundHasVisibleActivity = false;
+        this.activeTurnHasAssistantText = false;
+        this.userMessageIds = [];
+        this.emittedUserMessageIds = new Set();
+        this.rewindTurnAnchors = [];
+        this.pendingFreshSessionId = null;
+        this.cumulativeImageBase64Bytes = 0;
+        this.cumulativeImageWarnEmitted = false;
+        this.recentStderr = "";
+        this.closed = false;
+        this.hookEventHandlers = new Map();
+        this.handlePermissionRequest = async (toolName, input, options) => {
+            const requestId = `permission-${randomUUID()}`;
+            const kind = resolvePermissionKind(toolName, input);
+            const requestInput = normalizeClaudeAskUserQuestionRequestInput(toolName, input);
+            const metadata = {};
+            if (options.toolUseID) {
+                metadata.toolUseId = options.toolUseID;
+            }
+            if (toolName === "ExitPlanMode" && typeof input.plan === "string") {
+                metadata.planText = input.plan;
+            }
+            const toolDetail = kind === "tool"
+                ? mapClaudeRunningToolCall({
+                    name: toolName,
+                    callId: options.toolUseID ?? requestId,
+                    input,
+                    output: null,
+                })?.detail
+                : undefined;
+            const request = {
+                id: requestId,
+                provider: "claude",
+                name: toolName,
+                kind,
+                input: requestInput,
+                detail: toolDetail,
+                suggestions: options.suggestions?.map((suggestion) => ({
+                    ...suggestion,
+                })),
+                actions: kind === "plan" ? buildClaudePlanPermissionActions(this.planResumeMode) : undefined,
+                metadata: Object.keys(metadata).length ? metadata : undefined,
+            };
+            this.pushEvent({
+                type: "permission_requested",
+                provider: "claude",
+                request,
+            });
+            return await new Promise((resolve, reject) => {
+                const cleanupFns = [];
+                const cleanup = () => {
+                    while (cleanupFns.length) {
+                        const fn = cleanupFns.pop();
+                        try {
+                            fn?.();
+                        }
+                        catch {
+                            // ignore cleanup errors
+                        }
+                    }
+                };
+                const abortHandler = () => {
+                    this.pendingPermissions.delete(requestId);
+                    cleanup();
+                    reject(new Error("Permission request aborted"));
+                };
+                if (options?.signal) {
+                    if (options.signal.aborted) {
+                        abortHandler();
+                        return;
+                    }
+                    options.signal.addEventListener("abort", abortHandler, { once: true });
+                    cleanupFns.push(() => options.signal?.removeEventListener("abort", abortHandler));
+                }
+                this.pendingPermissions.set(requestId, {
+                    request,
+                    resolve,
+                    reject,
+                    cleanup,
+                });
+            });
+        };
+        this.config = config;
+        this.launchEnv = options.launchEnv;
+        this.agentId = options.agentId;
+        this.defaults = options.defaults;
+        this.runtimeSettings = options.runtimeSettings;
+        this.persistSession = options.persistSession;
+        this.logger = options.logger.child({ agentId: this.agentId });
+        this.queryFactory = options.queryFactory;
+        this.resolveBinary = options.resolveBinary;
+        this.contextUsage = new ClaudeContextUsageState(findClaudeModel(this.config.model)?.contextWindowMaxTokens);
+        const handle = options.handle;
+        if (handle) {
+            if (!handle.sessionId) {
+                throw new Error("Cannot resume: persistence handle has no sessionId");
+            }
+            this.claudeSessionId = handle.sessionId;
+            this.persistence = handle;
+            this.loadPersistedHistory(handle.sessionId);
+        }
+        else if (options.resumeSessionId) {
+            // Story 3.6 — Fork-resume: seed the SID so buildOptions() / PTY emits
+            // `--resume <sid>`. Do NOT set a persistence handle — Claude CLI forks to
+            // a NEW SID at spawn time and the SOURCE JSONL stays byte-identical (AC4:
+            // only WRITES fork; reads are fine).
+            this.claudeSessionId = options.resumeSessionId;
+            this.persistence = null;
+            // Load the source transcript into persistedHistory for DISPLAY only.
+            // loadPersistedHistory is a read-only fs.readFileSync, so the source
+            // stays byte-identical — but without it the resumed chat renders empty
+            // ("Start chatting…") until the next turn, even though Claude has the
+            // full context internally. The create handler calls
+            // hydrateTimelineFromProvider to stream this into the timeline.
+            this.loadPersistedHistory(options.resumeSessionId);
+        }
+        else {
+            this.claudeSessionId = null;
+            this.persistence = null;
+        }
+        // Validate mode if provided
+        if (config.modeId && !VALID_CLAUDE_MODES.has(config.modeId)) {
+            const validModesList = Array.from(VALID_CLAUDE_MODES).join(", ");
+            throw new Error(`Invalid mode '${config.modeId}' for Claude provider. Valid modes: ${validModesList}`);
+        }
+        this.currentMode = isPermissionMode(config.modeId) ? config.modeId : "default";
+        if (this.currentMode !== "plan") {
+            this.planResumeMode = this.currentMode;
+        }
+    }
+    get id() {
+        return this.claudeSessionId;
+    }
+    get features() {
+        return buildClaudeFeatures({
+            modelId: this.config.model,
+            fastModeEnabled: this.config.featureValues?.fast_mode === true,
+        });
+    }
+    async getRuntimeInfo() {
+        if (this.cachedRuntimeInfo) {
+            return { ...this.cachedRuntimeInfo };
+        }
+        const info = {
+            provider: "claude",
+            sessionId: this.claudeSessionId,
+            model: this.lastOptionsModel,
+            modeId: this.currentMode ?? null,
+            ...(this.lastRuntimeModel
+                ? {
+                    extra: {
+                        runtimeModel: this.lastRuntimeModel,
+                    },
+                }
+                : {}),
+        };
+        this.cachedRuntimeInfo = info;
+        return { ...info };
+    }
+    async run(prompt, options) {
+        const result = await runProviderTurn({
+            prompt,
+            runOptions: options,
+            startTurn: (p, o) => this.startTurn(p, o),
+            subscribe: (callback) => this.subscribe(callback),
+            getSessionId: () => this.claudeSessionId ?? "",
+            reduceFinalText: appendOrReplaceGrowingAssistantMessage,
+        });
+        this.cachedRuntimeInfo = {
+            provider: "claude",
+            sessionId: this.claudeSessionId,
+            model: this.lastOptionsModel,
+            modeId: this.currentMode ?? null,
+        };
+        if (!this.claudeSessionId) {
+            throw new Error("Session ID not set after run completed");
+        }
+        return result;
+    }
+    async startTurn(prompt, _options) {
+        if (this.closed) {
+            throw new Error("Claude session is closed");
+        }
+        if (this.activeForegroundTurnId) {
+            throw new Error("A foreground turn is already active");
+        }
+        const slashCommand = this.resolveSlashCommandInvocation(prompt);
+        if (slashCommand?.commandName === REWIND_COMMAND_NAME) {
+            const turnId = this.createTurnId("foreground");
+            this.activeForegroundTurnId = turnId;
+            this.transitionTurnState("foreground", "rewind command");
+            void this.executeRewindTurn(turnId, slashCommand);
+            return { turnId };
+        }
+        if (this.autonomousTurn) {
+            this.completeAutonomousTurn();
+        }
+        const turnId = this.createTurnId("foreground");
+        this.activeForegroundTurnId = turnId;
+        this.foregroundHasVisibleActivity = false;
+        this.activeTurnHasAssistantText = false;
+        this.contextUsage.beginTurn();
+        this.transitionTurnState("foreground", "foreground turn started");
+        this.clearRecentStderr();
+        let sdkMessage;
+        try {
+            sdkMessage = await this.toSdkUserMessage(prompt);
+        }
+        catch (error) {
+            this.finishForegroundTurn(this.buildTurnFailedEvent(error instanceof Error ? error.message : "Failed to prepare user message"));
+            return { turnId };
+        }
+        let cancelIssued = false;
+        const requestCancel = () => {
+            if (cancelIssued) {
+                return;
+            }
+            cancelIssued = true;
+            if (this.cancelCurrentTurn === requestCancel) {
+                this.cancelCurrentTurn = null;
+            }
+            this.rejectAllPendingPermissions(new Error("Permission request aborted"));
+            this.finishForegroundTurn({
+                type: "turn_canceled",
+                provider: "claude",
+                reason: "Interrupted",
+            });
+            void this.interruptActiveTurn().catch((error) => {
+                this.logger.warn({ err: error }, "Failed to interrupt during cancel");
+            });
+        };
+        this.cancelCurrentTurn = requestCancel;
+        this.notifySubscribers({ type: "turn_started", provider: "claude" });
+        try {
+            await this.ensureQuery();
+            if (!this.input) {
+                throw new Error("Claude session input stream not initialized");
+            }
+            this.startQueryPump();
+            this.input.push(sdkMessage);
+            setTimeout(() => {
+                if (this.activeForegroundTurnId === turnId) {
+                    this.emitSubmittedUserMessage(sdkMessage, turnId);
+                }
+            }, 0);
+        }
+        catch (error) {
+            this.finishForegroundTurn(this.buildTurnFailedEvent(error instanceof Error ? error.message : "Claude stream failed"));
+        }
+        return { turnId };
+    }
+    subscribe(callback) {
+        this.subscribers.add(callback);
+        return () => {
+            this.subscribers.delete(callback);
+        };
+    }
+    async interrupt() {
+        if (this.cancelCurrentTurn) {
+            this.cancelCurrentTurn();
+            return;
+        }
+        if (this.autonomousTurn) {
+            this.flushPendingToolCalls();
+            this.completeAutonomousTurn();
+        }
+        await this.interruptActiveTurn();
+    }
+    async *streamHistory() {
+        if (!this.historyPending || this.persistedHistory.length === 0) {
+            return;
+        }
+        const history = this.persistedHistory;
+        this.persistedHistory = [];
+        this.historyPending = false;
+        for (const entry of history) {
+            yield {
+                type: "timeline",
+                item: entry.item,
+                provider: "claude",
+                timestamp: entry.timestamp,
+            };
+        }
+    }
+    async getAvailableModes() {
+        return this.availableModes;
+    }
+    async getCurrentMode() {
+        return this.currentMode ?? null;
+    }
+    async setMode(modeId) {
+        // Validate mode
+        if (!VALID_CLAUDE_MODES.has(modeId)) {
+            const validModesList = Array.from(VALID_CLAUDE_MODES).join(", ");
+            throw new Error(`Invalid mode '${modeId}' for Claude provider. Valid modes: ${validModesList}`);
+        }
+        const normalized = isPermissionMode(modeId) ? modeId : "default";
+        assertClaudeAutoModeEligible(normalized, this.buildSdkEnv(this.config.extra?.claude));
+        const previousMode = this.currentMode;
+        const activeQuery = await this.ensureQuery();
+        if (this.activeTransport instanceof PtyTransport) {
+            // PTY path: claude 2.1.119 has no /mode or /permission-mode slash command.
+            // Force a session reload so the new spawn picks up --permission-mode <mode>.
+            await this.reloadAgentSession({ overrides: { permissionMode: normalized } });
+        }
+        else {
+            await activeQuery.setPermissionMode(normalized);
+        }
+        if (normalized === "plan") {
+            if (previousMode !== "plan") {
+                this.planResumeMode = previousMode;
+            }
+        }
+        else {
+            this.planResumeMode = normalized;
+        }
+        this.currentMode = normalized;
+    }
+    async setModel(modelId) {
+        const normalizedModelId = typeof modelId === "string" && modelId.trim().length > 0 ? modelId : null;
+        const activeQuery = await this.ensureQuery();
+        if (this.activeTransport instanceof PtyTransport) {
+            // PTY path: /model <name> slash command. Null/empty → omit write, state-only.
+            if (normalizedModelId !== null) {
+                await this.activeTransport.write(`/model ${normalizedModelId}\r`);
+            }
+        }
+        else {
+            await activeQuery.setModel(normalizedModelId ?? undefined);
+        }
+        // Shared self-state update — both transport paths.
+        this.config.model = normalizedModelId ?? undefined;
+        if (!claudeModelSupportsFastMode(this.config.model) && this.config.featureValues?.fast_mode) {
+            await this.applyFastModeFeature(false, activeQuery);
+        }
+        this.contextUsage.setInitialContextWindowMaxTokens(findClaudeModel(this.config.model)?.contextWindowMaxTokens);
+        this.lastOptionsModel = normalizedModelId ?? this.lastOptionsModel;
+        this.lastRuntimeModel = null;
+        this.cachedRuntimeInfo = null;
+        // Model change affects persistence metadata, so invalidate cached handle.
+        this.persistence = null;
+    }
+    async setThinkingOption(thinkingOptionId) {
+        const normalizedThinkingOptionId = typeof thinkingOptionId === "string" && thinkingOptionId.trim().length > 0
+            ? thinkingOptionId
+            : null;
+        if (!normalizedThinkingOptionId || normalizedThinkingOptionId === "default") {
+            this.config.thinkingOptionId = undefined;
+        }
+        else if (isClaudeThinkingOption(normalizedThinkingOptionId)) {
+            this.config.thinkingOptionId = normalizedThinkingOptionId;
+        }
+        else {
+            throw new Error(`Unknown thinking option: ${normalizedThinkingOptionId}`);
+        }
+        if (this.activeTransport instanceof PtyTransport) {
+            // PTY path: /effort <level> slash command, takes effect immediately.
+            // Do NOT set queryRestartNeeded — that's an SDK-only restart signal.
+            const effort = normalizedThinkingOptionId && normalizedThinkingOptionId !== "default"
+                ? normalizedThinkingOptionId
+                : "low";
+            await this.activeTransport.write(`/effort ${effort}\r`);
+            return;
+        }
+        this.queryRestartNeeded = true;
+        if (this.activeForegroundTurnId || this.autonomousTurn) {
+            return SETTING_APPLIES_NEXT_TURN_NOTICE;
+        }
+    }
+    /**
+     * Story 3.3 — PTY-path session reload hook.
+     *
+     * On the PTY transport, runtime config changes that require a respawn (e.g.
+     * permission mode) call this method. Default impl is a no-op stub so the
+     * unit tests can `vi.spyOn(session, "reloadAgentSession")` to assert the
+     * branch fires. The full integration is wired by agent-manager in a later
+     * story; until then this method updates the in-session `currentMode` so the
+     * next ensureQuery() rebuild picks up the new mode.
+     */
+    async reloadAgentSession(opts) {
+        if (opts?.overrides?.permissionMode) {
+            this.currentMode = opts.overrides.permissionMode;
+        }
+        // Force the next ensureQuery() to rebuild so the new spawn picks up the
+        // updated --permission-mode value.
+        this.queryRestartNeeded = true;
+    }
+    async setFeature(featureId, value) {
+        if (featureId !== "fast_mode") {
+            throw new Error(`Unknown Claude feature: ${featureId}`);
+        }
+        const enabled = Boolean(value);
+        if (enabled && !claudeModelSupportsFastMode(this.config.model)) {
+            throw new Error(`Claude fast mode is not available for model '${this.config.model ?? "default"}'`);
+        }
+        await this.applyFastModeFeature(enabled);
+    }
+    async applyFastModeFeature(enabled, query) {
+        this.config.featureValues = {
+            ...this.config.featureValues,
+            fast_mode: enabled,
+        };
+        const activeQuery = query ?? this.query;
+        if (activeQuery) {
+            await activeQuery.applyFlagSettings({ fastMode: enabled });
+        }
+        this.cachedRuntimeInfo = null;
+    }
+    getPendingPermissions() {
+        return Array.from(this.pendingPermissions.values()).map((entry) => entry.request);
+    }
+    getActiveBackgroundTaskCount() {
+        return this.backgroundTaskTracker.count;
+    }
+    /**
+     * Dismiss live background shell(s) the way a human would in the Claude Code
+     * CLI: drive Claude Code's own TUI over the PTY with its `ctrl+x ctrl+k` kill
+     * chord (sent twice — arm + confirm), killing the shell INSIDE Claude Code
+     * rather than via an external OS kill. Then clear our tracked set.
+     *
+     * Caveat: `ctrl+x ctrl+k` is Claude Code's *global* stop-background-work
+     * chord (no per-shell-by-id interactive binding exists), so we clear the
+     * whole set afterward. `taskId` is accepted for API symmetry/logging.
+     *
+     * Returns true if keystrokes were delivered to a live PTY-driven session. On
+     * the SDK transport (no TUI to drive) it falls back to untracking the id.
+     */
+    async dismissBackgroundTask(taskId) {
+        const transport = this.activeTransport;
+        if (transport instanceof PtyTransport && typeof transport.writeRaw === "function") {
+            for (const press of buildBackgroundKillPresses()) {
+                await transport.writeRaw(press);
+            }
+            this.backgroundTaskTracker.clear();
+            this.logger.debug({ taskId }, "Dismissed background shells via Claude Code ctrl+x ctrl+k");
+            return true;
+        }
+        // No interactive TUI to drive (e.g. SDK transport) — best-effort untrack.
+        return this.backgroundTaskTracker.remove(taskId);
+    }
+    async respondToPermission(requestId, response) {
+        const pending = this.pendingPermissions.get(requestId);
+        if (!pending) {
+            throw new Error(`No pending permission request with id '${requestId}'`);
+        }
+        this.pendingPermissions.delete(requestId);
+        pending.cleanup?.();
+        if (response.behavior === "allow") {
+            if (pending.request.kind === "plan") {
+                const selectedActionId = response.selectedActionId;
+                const shouldResumePriorMode = selectedActionId === "implement_resume" && this.planResumeMode === "bypassPermissions";
+                const targetMode = shouldResumePriorMode
+                    ? "bypassPermissions"
+                    : "acceptEdits";
+                await this.setMode(targetMode);
+                this.pushToolCall(mapClaudeCompletedToolCall({
+                    name: "plan_approval",
+                    callId: pending.request.id,
+                    input: pending.request.input ?? null,
+                    output: {
+                        approved: true,
+                        actionId: selectedActionId ?? "implement",
+                    },
+                }));
+            }
+            const updatedInput = pending.request.kind === "question"
+                ? normalizeClaudeAskUserQuestionUpdatedInput(response.updatedInput, pending.request.input ?? undefined)
+                : (response.updatedInput ?? pending.request.input ?? {});
+            const result = {
+                behavior: "allow",
+                updatedInput,
+                updatedPermissions: this.normalizePermissionUpdates(response.updatedPermissions),
+            };
+            pending.resolve(result);
+        }
+        else {
+            if (pending.request.kind === "tool") {
+                this.pushToolCall(mapClaudeFailedToolCall({
+                    name: pending.request.name,
+                    callId: (typeof pending.request.metadata?.toolUseId === "string"
+                        ? pending.request.metadata.toolUseId
+                        : null) ?? pending.request.id,
+                    input: pending.request.input ?? null,
+                    output: null,
+                    error: { message: response.message ?? "Permission denied" },
+                }));
+            }
+            const result = {
+                behavior: "deny",
+                message: response.message ?? "Permission request denied",
+                interrupt: response.interrupt,
+            };
+            pending.resolve(result);
+        }
+        this.pushEvent({
+            type: "permission_resolved",
+            provider: "claude",
+            requestId,
+            resolution: response,
+        });
+    }
+    describePersistence() {
+        if (this.persistence) {
+            return this.persistence;
+        }
+        if (!this.claudeSessionId) {
+            return null;
+        }
+        this.persistence = {
+            provider: "claude",
+            sessionId: this.claudeSessionId,
+            nativeHandle: this.claudeSessionId,
+            metadata: { ...this.config },
+        };
+        return this.persistence;
+    }
+    async close() {
+        this.logger.trace({
+            agentId: this.agentId,
+            provider: "claude",
+            sessionId: this.claudeSessionId,
+            turnId: this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? undefined,
+            turnState: this.turnState,
+            hasQuery: Boolean(this.query),
+            hasInput: Boolean(this.input),
+            hasActiveForegroundTurnId: Boolean(this.activeForegroundTurnId),
+        }, "provider.claude.session_close.start");
+        this.closed = true;
+        this.rejectAllPendingPermissions(new Error("Claude session closed"));
+        this.cancelCurrentTurn?.();
+        this.subscribers.clear();
+        this.activeForegroundTurnId = null;
+        this.autonomousTurn = null;
+        this.cancelCurrentTurn = null;
+        this.turnState = "idle";
+        this.sidechainTracker.clear();
+        this.backgroundTaskTracker.clear();
+        this.input?.end();
+        this.query?.close?.();
+        await this.awaitWithTimeout(this.query?.interrupt?.(), "close query interrupt");
+        await this.awaitWithTimeout(this.query?.return?.(), "close query return");
+        this.query = null;
+        this.input = null;
+        // Terminate the entire process tree (claude + MCP children) to prevent
+        // orphan accumulation. The SDK's internal cleanup may only kill the
+        // direct child process.
+        if (this.childProcess) {
+            const result = await terminateWithTreeKill(this.childProcess, {
+                gracefulTimeoutMs: 2000,
+                forceTimeoutMs: 2000,
+            });
+            if (result === "kill-timeout") {
+                this.logger.warn({ pid: this.childProcess.pid, agentId: this.agentId }, "Claude process tree did not report exit after SIGKILL");
+            }
+            this.childProcess = null;
+        }
+        if (this.persistSession === false && this.claudeSessionId) {
+            // Claude Code currently ignores --no-session-persistence outside --print mode
+            // (see `claude --help`), so the SDK's persistSession=false is silently dropped
+            // in stream-json mode. Sweep the transcript ourselves so ephemeral runs
+            // (metadata generator, branch-name generator) don't show up as resumable.
+            const historyPath = this.resolveHistoryPath(this.claudeSessionId);
+            if (historyPath) {
+                try {
+                    await promises.rm(historyPath, { force: true });
+                }
+                catch (error) {
+                    this.logger.warn({ err: error, historyPath, claudeSessionId: this.claudeSessionId }, "Failed to delete ephemeral Claude session transcript");
+                }
+            }
+        }
+        this.logger.trace({
+            agentId: this.agentId,
+            provider: "claude",
+            sessionId: this.claudeSessionId,
+            turnState: this.turnState,
+        }, "provider.claude.session_close.complete");
+    }
+    async listCommands() {
+        const q = await this.ensureQuery();
+        const commands = await q.supportedCommands();
+        const commandMap = new Map();
+        for (const cmd of commands) {
+            if (!commandMap.has(cmd.name)) {
+                commandMap.set(cmd.name, {
+                    name: cmd.name,
+                    description: cmd.description,
+                    argumentHint: cmd.argumentHint,
+                    kind: classifyClaudeSlashCommand(cmd.name),
+                });
+            }
+        }
+        if (!commandMap.has(REWIND_COMMAND_NAME)) {
+            commandMap.set(REWIND_COMMAND_NAME, REWIND_COMMAND);
+        }
+        return Array.from(commandMap.values()).sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async revertConversation(input) {
+        const target = this.resolveConversationRewindTarget(input.messageId);
+        if (target.kind === "fresh-session") {
+            this.startFreshConversationSession();
+            return;
+        }
+        await revertClaudeConversation({
+            sdk: realClaudeRewindSdk,
+            sessionId: this.claudeSessionId,
+            messageId: target.messageId,
+            resolveMessageId: (messageId) => this.resolveClaudeMessageId(messageId),
+            setSessionId: (sessionId) => {
+                this.rebindConversationSession(sessionId);
+            },
+        });
+    }
+    async revertFiles(input) {
+        const messageId = await this.resolveClaudeMessageId(input.messageId);
+        await revertClaudeFiles({
+            query: await this.ensureQuery(),
+            messageId,
+        });
+    }
+    async revertBoth(input) {
+        await this.revertFiles(input);
+        await this.revertConversation(input);
+    }
+    resolveSlashCommandInvocation(prompt) {
+        if (typeof prompt !== "string") {
+            return null;
+        }
+        const parsed = this.parseSlashCommandInput(prompt);
+        if (!parsed) {
+            return null;
+        }
+        return parsed.commandName === REWIND_COMMAND_NAME ? parsed : null;
+    }
+    parseSlashCommandInput(text) {
+        const trimmed = text.trim();
+        if (!trimmed.startsWith("/") || trimmed.length <= 1) {
+            return null;
+        }
+        const withoutPrefix = trimmed.slice(1);
+        const firstWhitespaceIdx = withoutPrefix.search(/\s/);
+        const commandName = firstWhitespaceIdx === -1 ? withoutPrefix : withoutPrefix.slice(0, firstWhitespaceIdx);
+        if (!commandName || commandName.includes("/")) {
+            return null;
+        }
+        const rawArgs = firstWhitespaceIdx === -1 ? "" : withoutPrefix.slice(firstWhitespaceIdx + 1).trim();
+        return rawArgs.length > 0
+            ? { commandName, args: rawArgs, rawInput: trimmed }
+            : { commandName, rawInput: trimmed };
+    }
+    buildRewindSuccessMessage(targetUserMessageId, rewindResult) {
+        const fileCount = Array.isArray(rewindResult.filesChanged)
+            ? rewindResult.filesChanged.length
+            : undefined;
+        const stats = [];
+        if (typeof fileCount === "number") {
+            stats.push(`${fileCount} file${fileCount === 1 ? "" : "s"}`);
+        }
+        if (typeof rewindResult.insertions === "number") {
+            stats.push(`${rewindResult.insertions} insertions`);
+        }
+        if (typeof rewindResult.deletions === "number") {
+            stats.push(`${rewindResult.deletions} deletions`);
+        }
+        if (stats.length > 0) {
+            return `Rewound tracked files to message ${targetUserMessageId} (${stats.join(", ")}).`;
+        }
+        return `Rewound tracked files to message ${targetUserMessageId}.`;
+    }
+    async attemptRewind(args) {
+        if (typeof args === "string" && args.trim().length > 0) {
+            const candidate = args.trim().split(/\s+/)[0] ?? "";
+            if (!UUID_PATTERN.test(candidate)) {
+                return {
+                    messageId: null,
+                    error: "Invalid message UUID. Usage: /rewind <user_message_uuid> or /rewind",
+                };
+            }
+            const rewindResult = await this.rewindFilesOnce(candidate);
+            if (rewindResult.canRewind) {
+                return { messageId: candidate, result: rewindResult };
+            }
+            return {
+                messageId: null,
+                error: rewindResult.error ?? `No file checkpoint found for message ${candidate}.`,
+            };
+        }
+        const candidates = this.getRewindCandidateUserMessageIds();
+        if (candidates.length === 0) {
+            return {
+                messageId: null,
+                error: "No prior user message available to rewind. Use /rewind <user_message_uuid>.",
+            };
+        }
+        let lastError;
+        for (const candidate of candidates) {
+            try {
+                const rewindResult = await this.rewindFilesOnce(candidate);
+                if (rewindResult.canRewind) {
+                    return { messageId: candidate, result: rewindResult };
+                }
+                if (rewindResult.error) {
+                    lastError = rewindResult.error;
+                }
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : "Failed to rewind tracked files.";
+            }
+        }
+        return {
+            messageId: null,
+            error: lastError ?? "No rewind checkpoints are currently available for this session.",
+        };
+    }
+    async rewindFilesOnce(messageId) {
+        try {
+            const activeQuery = await this.ensureFreshQuery();
+            return await activeQuery.rewindFiles(messageId, { dryRun: false });
+        }
+        catch (error) {
+            // The Claude SDK transport can close after a rewind call.
+            // If that happens, mark the query stale so a follow-up attempt uses a fresh query.
+            this.queryRestartNeeded = true;
+            throw error;
+        }
+    }
+    async ensureFreshQuery() {
+        if (this.query) {
+            this.queryRestartNeeded = true;
+        }
+        return this.ensureQuery();
+    }
+    getRewindCandidateUserMessageIds() {
+        const candidates = [];
+        const pushUnique = (value) => {
+            if (typeof value === "string" && value.length > 0 && !candidates.includes(value)) {
+                candidates.push(value);
+            }
+        };
+        for (let idx = this.persistedHistory.length - 1; idx >= 0; idx -= 1) {
+            const entry = this.persistedHistory[idx];
+            if (entry?.item.type === "user_message") {
+                pushUnique(entry.item.messageId);
+            }
+        }
+        for (let idx = this.userMessageIds.length - 1; idx >= 0; idx -= 1) {
+            pushUnique(this.userMessageIds[idx]);
+        }
+        return candidates;
+    }
+    rebindConversationSession(sessionId) {
+        const oldSessionId = this.claudeSessionId;
+        this.claudeSessionId = sessionId;
+        this.pendingFreshSessionId = null;
+        this.persistence = null;
+        this.cachedRuntimeInfo = null;
+        this.queryRestartNeeded = true;
+        this.persistedHistory = [];
+        this.historyPending = false;
+        this.userMessageIds = [];
+        this.emittedUserMessageIds.clear();
+        this.rewindTurnAnchors.length = 0;
+        this.loadPersistedHistory(sessionId);
+        if (oldSessionId && oldSessionId !== sessionId) {
+            this.dispatchEvents([
+                {
+                    type: "timeline",
+                    provider: "claude",
+                    item: this.createClaudeSessionChangedNotice(oldSessionId, sessionId),
+                },
+                {
+                    type: "thread_started",
+                    provider: "claude",
+                    sessionId,
+                },
+            ]);
+        }
+    }
+    startFreshConversationSession() {
+        const sessionId = randomUUID();
+        this.claudeSessionId = sessionId;
+        this.pendingFreshSessionId = sessionId;
+        this.persistence = null;
+        this.cachedRuntimeInfo = null;
+        this.queryRestartNeeded = true;
+        this.persistedHistory = [];
+        this.historyPending = false;
+        this.userMessageIds = [];
+        this.emittedUserMessageIds.clear();
+        this.rewindTurnAnchors.length = 0;
+    }
+    rememberUserMessageId(messageId) {
+        if (typeof messageId !== "string" || messageId.length === 0) {
+            return;
+        }
+        const last = this.userMessageIds[this.userMessageIds.length - 1];
+        if (last === messageId) {
+            return;
+        }
+        this.userMessageIds.push(messageId);
+    }
+    /**
+     * Story 4.1 — Resolve the effective transport for this session and cache it.
+     * Called once per session lifetime; further calls return the cached value.
+     * Epic 3 wiring will use this to choose between SdkTransport and PtyTransport.
+     */
+    ensureTransport() {
+        if (this.resolvedTransport)
+            return this.resolvedTransport;
+        this.resolvedTransport = resolveClaudeTransport(this.runtimeSettings?.transport);
+        this.fireTransportSpawnedTelemetry(this.resolvedTransport);
+        return this.resolvedTransport;
+    }
+    /**
+     * Story 4.4 — Fire `agent.transport.spawned` once per session. Probes
+     * `claude --version` in the background; emits with `version: "unknown"` if
+     * the probe is not yet resolved or fails. Never throws.
+     */
+    fireTransportSpawnedTelemetry(transport) {
+        if (this.transportSpawnedTelemetryFired)
+            return;
+        this.transportSpawnedTelemetryFired = true;
+        const emit = (version) => {
+            try {
+                trackTransportSpawned({ transport, provider: "claude", version }, this.logger);
+            }
+            catch {
+                // belt-and-suspenders: telemetry must never crash the session
+            }
+        };
+        if (this.claudeVersion) {
+            emit(this.claudeVersion);
+            return;
+        }
+        resolveClaudeVersion(this.runtimeSettings)
+            .then((version) => {
+            const resolved = version ?? "unknown";
+            this.claudeVersion = resolved;
+            emit(resolved);
+            return resolved;
+        })
+            .catch(() => {
+            emit("unknown");
+        });
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Rewind anchor bookkeeping. Ported from the SDK-transport implementation;
+    // currently inert under the PTY transport (the PTY path doesn't call the
+    // remember*/resolveConversationRewindTarget paths yet). Restored so the
+    // file compiles end-to-end; the PTY-aware rewind rewrite is tracked in
+    // docs/tech-debt.md. Do not delete without coordinating the rewrite.
+    // ──────────────────────────────────────────────────────────────────────────
+    rememberEmittedUserMessageId(messageId) {
+        if (typeof messageId !== "string" || messageId.length === 0) {
+            return;
+        }
+        this.emittedUserMessageIds.add(messageId);
+    }
+    rememberRewindUserAnchor(userMessageId) {
+        if (typeof userMessageId !== "string" || userMessageId.length === 0) {
+            return;
+        }
+        if (this.rewindTurnAnchors.some((anchor) => anchor.userMessageId === userMessageId)) {
+            return;
+        }
+        this.rewindTurnAnchors.push({
+            userMessageId,
+            assistantMessageId: null,
+        });
+    }
+    rememberRewindAssistantAnchor(assistantMessageId) {
+        if (typeof assistantMessageId !== "string" || assistantMessageId.length === 0) {
+            return;
+        }
+        for (let index = this.rewindTurnAnchors.length - 1; index >= 0; index -= 1) {
+            const anchor = this.rewindTurnAnchors[index];
+            if (!anchor) {
+                continue;
+            }
+            anchor.assistantMessageId = assistantMessageId;
+            return;
+        }
+    }
+    rememberTranscriptProgress(message, messageId) {
+        if (!messageId) {
+            return;
+        }
+        if (message.type === "user" &&
+            !isSyntheticUserEntry(message) &&
+            !isToolResultUserEntry(message)) {
+            this.rememberRewindUserAnchor(messageId);
+            return;
+        }
+        if (message.type === "assistant") {
+            this.rememberRewindAssistantAnchor(messageId);
+            return;
+        }
+        if (message.type === "stream_event") {
+            const event = toObjectRecord(message.event) ?? {};
+            const eventType = readTrimmedString(event.type);
+            if (eventType === "message_start") {
+                this.rememberRewindAssistantAnchor(messageId);
+            }
+            return;
+        }
+    }
+    resolveClaudeMessageId(messageId) {
+        return messageId;
+    }
+    resolveConversationRewindTarget(messageId) {
+        const targetUserMessageId = this.resolveClaudeMessageId(messageId);
+        const index = this.rewindTurnAnchors.findIndex((anchor) => anchor.userMessageId === targetUserMessageId);
+        if (index < 0) {
+            throw new Error(`Claude rewind target ${messageId} is not in the tracked conversation`);
+        }
+        if (index === 0) {
+            return { kind: "fresh-session" };
+        }
+        const previousTurn = this.rewindTurnAnchors[index - 1];
+        if (!previousTurn?.assistantMessageId) {
+            throw new Error(`Claude rewind cannot preserve turn ${index} because its assistant response id was not observed`);
+        }
+        return { kind: "fork", messageId: previousTurn.assistantMessageId };
+    }
+    async ensureQuery() {
+        // Story 4.1 — Cache the resolved transport on first use. Even though the
+        // current path always instantiates SdkTransport, recording the choice means
+        // setMode/setModel/swapAgentProvider can read it without re-probing.
+        this.ensureTransport();
+        if (this.query && !this.queryRestartNeeded) {
+            return this.query;
+        }
+        if (this.queryRestartNeeded && this.query) {
+            const oldQuery = this.query;
+            const oldInput = this.input;
+            // Null out query/input BEFORE awaiting the old iterator's return so the
+            // old pump sees this.query !== activeQuery and skips failActiveTurns.
+            this.query = null;
+            this.input = null;
+            this.queryPumpPromise = null;
+            this.queryRestartNeeded = false;
+            oldInput?.end();
+            oldQuery.close?.();
+            try {
+                await oldQuery.return?.();
+            }
+            catch {
+                /* ignore */
+            }
+            // Tree-kill the old process tree now that the SDK has cleaned up.
+            // If we skip this, MCP children of the previous claude process can
+            // survive as orphans when the session spawns a replacement query.
+            if (this.childProcess) {
+                await terminateWithTreeKill(this.childProcess, {
+                    gracefulTimeoutMs: 2000,
+                    forceTimeoutMs: 2000,
+                }).catch(() => {
+                    /* process may already be dead */
+                });
+                this.childProcess = null;
+            }
+        }
+        // Preserve claudeSessionId across query recreation so buildOptions() passes
+        // resume: sessionId and the new query continues the existing conversation.
+        this.persistence = null;
+        const input = createAsyncMessageInput();
+        const options = await this.buildOptions();
+        this.logger.debug({ options: summarizeClaudeOptionsForLog(options) }, "claude query");
+        this.input = input;
+        if (this.runtimeSettings?.transport === "pty") {
+            // Interactive-PTY path (Max-plan billing). Reconstructs the SDKMessage stream from
+            // the session transcript instead of --output-format stream-json. See
+            // pty-session-launcher / PtyQuery for the details.
+            //
+            // OPT-IN ONLY: gated on an EXPLICIT `transport: "pty"` — deliberately NOT on
+            // `resolvedTransport`/"auto", because resolveClaudeTransport(undefined) resolves to
+            // "pty" whenever node-pty is present, which would silently move every agent onto the
+            // (ToS-gray) Max-plan path. Rollout to auto is a separate, later decision.
+            const freshId = this.pendingFreshSessionId;
+            const resumeId = !freshId && this.claudeSessionId ? this.claudeSessionId : undefined;
+            const ptySessionId = freshId ?? resumeId ?? randomUUID();
+            const ptySession = await createPtySession({
+                binary: await this.resolveBinary(),
+                cwd: this.config.cwd,
+                sessionId: ptySessionId,
+                resume: Boolean(resumeId),
+                model: this.config.model,
+                permissionMode: this.currentMode,
+                appendSystemPrompt: this.buildAppendedSystemPrompt(),
+                input: input.iterable,
+                runtimeSettings: this.runtimeSettings,
+                launchEnv: this.launchEnv,
+                mcpServers: this.config.mcpServers
+                    ? this.normalizeMcpServers(this.config.mcpServers)
+                    : undefined,
+                logger: this.logger,
+            });
+            this.activeTransport = ptySession.transport;
+            this.query = ptySession.query;
+            // Pin the resolved session id so a later query restart resumes this conversation.
+            this.claudeSessionId = ptySessionId;
+        }
+        else {
+            const sdkTransport = new SdkTransport({
+                runtimeSettings: this.runtimeSettings,
+                launchEnv: this.launchEnv,
+                queryFactory: this.queryFactory,
+                logger: this.logger,
+            });
+            this.activeTransport = sdkTransport;
+            this.query = sdkTransport.createQuery({ prompt: input.iterable, options });
+        }
+        // Apply initial flag-settings to the freshly-created query. The options
+        // we passed to createQuery seeded fastMode in settings, but the SDK's
+        // applyFlagSettings is what actually flips the per-turn flag on the live
+        // query; ensure both paths are in sync from turn 1.
+        if (this.config.featureValues?.fast_mode === true) {
+            try {
+                await this.query.applyFlagSettings({ fastMode: true });
+            }
+            catch (err) {
+                this.logger.warn({ err }, "applyFlagSettings({fastMode:true}) failed at ensureQuery");
+            }
+        }
+        // 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({
+                agentId: this.agentId,
+                provider: "claude",
+                sessionId: this.claudeSessionId,
+                turnId: this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? undefined,
+                label,
+            }, "provider.claude.query_operation.skip");
+            return;
+        }
+        const startedAt = Date.now();
+        this.logger.trace({
+            agentId: this.agentId,
+            provider: "claude",
+            sessionId: this.claudeSessionId,
+            turnId: this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? undefined,
+            label,
+        }, "provider.claude.query_operation.start");
+        try {
+            await withTimeout(promise, 3000, "timeout");
+            this.logger.trace({
+                agentId: this.agentId,
+                provider: "claude",
+                sessionId: this.claudeSessionId,
+                turnId: this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? undefined,
+                label,
+                durationMs: Date.now() - startedAt,
+            }, "provider.claude.query_operation.settled");
+        }
+        catch (error) {
+            this.logger.warn({ err: error, label }, "Claude query operation did not settle cleanly");
+        }
+    }
+    resolveThinkingConfig() {
+        const thinkingOptionId = this.config.thinkingOptionId && this.config.thinkingOptionId !== "default"
+            ? this.config.thinkingOptionId
+            : undefined;
+        if (thinkingOptionId === CLAUDE_ULTRACODE_THINKING_OPTION_ID) {
+            return { thinking: { type: "adaptive" }, effort: "xhigh", ultracode: true };
+        }
+        if (thinkingOptionId && isClaudeThinkingEffort(thinkingOptionId)) {
+            return { thinking: { type: "adaptive" }, effort: thinkingOptionId, ultracode: false };
+        }
+        return { thinking: undefined, effort: undefined, ultracode: false };
+    }
+    buildAppendedSystemPrompt() {
+        return (composeSystemPromptParts(this.config.systemPrompt, this.config.daemonAppendSystemPrompt) ?? "");
+    }
+    buildSdkEnv(extraClaudeOptions) {
+        return createProviderEnv({
+            baseEnv: process.env,
+            runtimeSettings: this.runtimeSettings,
+            overlays: [
+                extraClaudeOptions?.env,
+                {
+                    // Increase MCP timeouts for long-running tool calls (10 minutes)
+                    MCP_TIMEOUT: "600000",
+                    MCP_TOOL_TIMEOUT: "600000",
+                },
+                this.launchEnv,
+            ],
+        });
+    }
+    async buildOptions() {
+        const { thinking, effort, ultracode } = this.resolveThinkingConfig();
+        const appendedSystemPrompt = this.buildAppendedSystemPrompt();
+        const extraClaudeOptions = this.config.extra?.claude;
+        const settingsOptions = this.buildSettingsOptions(extraClaudeOptions, { ultracode });
+        const sdkEnv = this.buildSdkEnv(extraClaudeOptions);
+        assertClaudeAutoModeEligible(this.currentMode, sdkEnv);
+        const claudeBinary = await this.resolveBinary();
+        this.logger.debug({
+            claudeBinary,
+            pathEnvKey: resolvePathEnvKey(),
+            pathIncludesClaudeLocalBin: (process.env["Path"] ?? process.env["PATH"] ?? "")
+                .toLowerCase()
+                .includes("\\.local\\bin"),
+        }, "Resolved Claude executable");
+        const sessionBinding = {};
+        if (this.pendingFreshSessionId) {
+            sessionBinding.sessionId = this.pendingFreshSessionId;
+        }
+        else if (this.claudeSessionId) {
+            sessionBinding.resume = this.claudeSessionId;
+        }
+        const base = {
+            cwd: this.config.cwd,
+            includePartialMessages: true,
+            permissionMode: this.currentMode,
+            // Dynamic mode switching can recreate the underlying Claude query. Keep the
+            // bypass launch capability available so later setPermissionMode("bypassPermissions")
+            // calls do not fail after a model/thinking/rewind-driven restart.
+            allowDangerouslySkipPermissions: true,
+            agents: this.defaults?.agents,
+            canUseTool: this.handlePermissionRequest,
+            pathToClaudeCodeExecutable: claudeBinary,
+            // Use Claude Code preset system prompt and load CLAUDE.md files
+            // Append provider-agnostic system prompts for agents.
+            systemPrompt: {
+                type: "preset",
+                preset: "claude_code",
+                append: appendedSystemPrompt,
+            },
+            settingSources: CLAUDE_SETTING_SOURCES,
+            stderr: (data) => {
+                this.captureStderr(data);
+                this.logger.error({ stderr: data.trim() }, "Claude Agent SDK stderr");
+            },
+            // Required for provider-level /rewind support.
+            enableFileCheckpointing: true,
+            // If we have a session ID from a previous query (e.g., after interrupt),
+            // resume that session to continue the conversation history.
+            ...sessionBinding,
+            ...(thinking ? { thinking } : {}),
+            ...(effort ? { effort } : {}),
+            ...extraClaudeOptions,
+            ...settingsOptions,
+            ...(this.persistSession === undefined ? {} : { persistSession: this.persistSession }),
+            env: sdkEnv,
+        };
+        if (this.config.mcpServers) {
+            base.mcpServers = this.normalizeMcpServers(this.config.mcpServers);
+        }
+        if (this.config.model) {
+            base.model = this.config.model;
+        }
+        this.lastOptionsModel = base.model ?? null;
+        if (this.claudeSessionId && !this.pendingFreshSessionId) {
+            base.resume = this.claudeSessionId;
+        }
+        if (this.runtimeSettings?.disallowedTools?.length) {
+            base.disallowedTools = [
+                ...(base.disallowedTools ?? []),
+                ...this.runtimeSettings.disallowedTools,
+            ];
+        }
+        return base;
+    }
+    buildSettingsOptions(extraClaudeOptions, input) {
+        const fastMode = this.resolveFastModeSetting();
+        if (fastMode === null && !input.ultracode) {
+            return {};
+        }
+        return {
+            settings: mergeClaudeSettings(extraClaudeOptions?.settings, {
+                ...(fastMode === null ? {} : { fastMode }),
+                ...(input.ultracode ? { ultracode: true } : {}),
+            }),
+        };
+    }
+    resolveFastModeSetting() {
+        if (!claudeModelSupportsFastMode(this.config.model)) {
+            return null;
+        }
+        return this.config.featureValues?.fast_mode === true;
+    }
+    normalizeMcpServers(servers) {
+        const result = {};
+        for (const [name, config] of Object.entries(servers)) {
+            result[name] = toClaudeSdkMcpConfig(config);
+        }
+        return result;
+    }
+    async toSdkUserMessage(prompt) {
+        const content = [];
+        if (Array.isArray(prompt)) {
+            for (const chunk of prompt) {
+                if (chunk.type === "text") {
+                    content.push({ type: "text", text: chunk.text });
+                }
+                else if (chunk.type === "image") {
+                    if (isImageMimeType(chunk.mimeType)) {
+                        const compressed = await compressImageForApi(chunk.data, chunk.mimeType, this.logger);
+                        this.enforceCumulativeImageBudget(compressed.compressedBytes);
+                        this.logger.debug({
+                            sourceMimeType: chunk.mimeType,
+                            originalBytes: compressed.originalBytes,
+                            compressedBytes: compressed.compressedBytes,
+                            cumulativeBytes: this.cumulativeImageBase64Bytes,
+                        }, "Compressed inline image before forwarding to Claude SDK");
+                        content.push({
+                            type: "image",
+                            source: {
+                                type: "base64",
+                                media_type: compressed.mediaType,
+                                data: compressed.data,
+                            },
+                        });
+                    }
+                }
+                else {
+                    content.push({ type: "text", text: renderPromptAttachmentAsText(chunk) });
+                }
+            }
+        }
+        else {
+            content.push({ type: "text", text: prompt });
+        }
+        const messageId = randomUUID();
+        this.rememberUserMessageId(messageId);
+        return {
+            type: "user",
+            message: {
+                role: "user",
+                content,
+            },
+            parent_tool_use_id: null,
+            uuid: messageId,
+            session_id: this.claudeSessionId ?? "",
+        };
+    }
+    enforceCumulativeImageBudget(addedBytes) {
+        const projected = this.cumulativeImageBase64Bytes + addedBytes;
+        if (projected > CUMULATIVE_IMAGE_LIMIT_BYTES) {
+            const limitMb = (CUMULATIVE_IMAGE_LIMIT_BYTES / (1024 * 1024)).toFixed(0);
+            const projectedMb = (projected / (1024 * 1024)).toFixed(1);
+            throw new Error(`Aborting image attach: cumulative inline images in this session would reach ${projectedMb}MB, ` +
+                `over the ${limitMb}MB safety limit set to stay under Anthropic's 32MB single-request cap. ` +
+                "Start a new agent session to clear the image history, or send fewer/smaller images in this one.");
+        }
+        this.cumulativeImageBase64Bytes = projected;
+        if (!this.cumulativeImageWarnEmitted &&
+            this.cumulativeImageBase64Bytes > CUMULATIVE_IMAGE_WARN_BYTES) {
+            this.cumulativeImageWarnEmitted = true;
+            this.logger.warn({
+                cumulativeBytes: this.cumulativeImageBase64Bytes,
+                warnThresholdBytes: CUMULATIVE_IMAGE_WARN_BYTES,
+                hardLimitBytes: CUMULATIVE_IMAGE_LIMIT_BYTES,
+            }, "Cumulative inline image bytes nearing per-session safety limit; further images may be rejected");
+        }
+    }
+    transitionTurnState(next, reason) {
+        if (this.turnState === next) {
+            return;
+        }
+        this.logger.debug({ from: this.turnState, to: next, reason }, "Claude turn state transition");
+        this.turnState = next;
+    }
+    syncTurnState(reason) {
+        if (this.activeForegroundTurnId) {
+            this.transitionTurnState("foreground", reason);
+            return;
+        }
+        if (this.autonomousTurn) {
+            this.transitionTurnState("autonomous", reason);
+            return;
+        }
+        this.transitionTurnState("idle", reason);
+    }
+    isAbortError(message) {
+        const errors = "errors" in message && Array.isArray(message.errors) ? message.errors : [];
+        return errors.some((e) => /\baborted\b/i.test(e));
+    }
+    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() {
+        return this.recentStderr.trim() || undefined;
+    }
+    async awaitRecentStderrAfterProcessExit(error) {
+        if (this.getRecentStderrDiagnostic()) {
+            return;
+        }
+        const message = errorToMessageString(error);
+        if (!/\bprocess exited with code\b/i.test(message) &&
+            !/\bterminated by signal\b/i.test(message)) {
+            return;
+        }
+        const startedAt = Date.now();
+        while (!this.closed && !this.getRecentStderrDiagnostic()) {
+            if (Date.now() - startedAt >= STDERR_FLUSH_WAIT_MS) {
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, STDERR_FLUSH_POLL_INTERVAL_MS));
+        }
+    }
+    createTurnId(owner) {
+        return `${owner}-turn-${this.nextTurnOrdinal++}`;
+    }
+    isTerminalTurnEvent(event) {
+        return (event.type === "turn_completed" ||
+            event.type === "turn_failed" ||
+            event.type === "turn_canceled");
+    }
+    async executeRewindTurn(_turnId, invocation) {
+        this.notifySubscribers({ type: "turn_started", provider: "claude" });
+        try {
+            const rewindAttempt = await this.attemptRewind(invocation.args);
+            if (!rewindAttempt.messageId || !rewindAttempt.result) {
+                this.finishForegroundTurn({
+                    type: "turn_failed",
+                    provider: "claude",
+                    error: rewindAttempt.error ??
+                        "No prior user message available to rewind. Use /rewind <user_message_uuid>.",
+                });
+                return;
+            }
+            this.notifySubscribers({
+                type: "timeline",
+                provider: "claude",
+                item: {
+                    type: "assistant_message",
+                    text: this.buildRewindSuccessMessage(rewindAttempt.messageId, rewindAttempt.result),
+                },
+            });
+            this.finishForegroundTurn({ type: "turn_completed", provider: "claude" });
+        }
+        catch (error) {
+            this.finishForegroundTurn({
+                type: "turn_failed",
+                provider: "claude",
+                error: error instanceof Error ? error.message : "Failed to rewind tracked files",
+            });
+        }
+    }
+    shouldRecoverInterruptedQueryAbort(error, consecutiveRecoveries) {
+        if (consecutiveRecoveries >= 3) {
+            return false;
+        }
+        let message;
+        if (typeof error === "string") {
+            message = error;
+        }
+        else if (error instanceof Error) {
+            message = `${error.message}\n${error.stack ?? ""}`;
+        }
+        else {
+            message = JSON.stringify(error);
+        }
+        return message.toLowerCase().includes("request was aborted");
+    }
+    finishForegroundTurn(event) {
+        if (event.type === "turn_failed" || event.type === "turn_canceled") {
+            this.flushPendingToolCalls();
+        }
+        this.notifySubscribers(event);
+        this.activeForegroundTurnId = null;
+        this.cancelCurrentTurn = null;
+        this.activeTurnHasAssistantText = false;
+        this.syncTurnState("foreground turn terminal");
+    }
+    dispatchEvents(events) {
+        let terminalSeen = false;
+        for (const event of events) {
+            this.notifySubscribers(event);
+            terminalSeen || (terminalSeen = this.isTerminalTurnEvent(event));
+        }
+        if (terminalSeen) {
+            if (this.activeForegroundTurnId) {
+                this.activeForegroundTurnId = null;
+                this.cancelCurrentTurn = null;
+                this.activeTurnHasAssistantText = false;
+                this.syncTurnState("foreground turn terminal");
+            }
+            else if (this.autonomousTurn) {
+                this.autonomousTurn = null;
+                this.activeTurnHasAssistantText = false;
+                this.syncTurnState("autonomous turn terminal");
+            }
+        }
+    }
+    startAutonomousTurn() {
+        if (this.autonomousTurn) {
+            return;
+        }
+        this.autonomousTurn = {
+            id: this.createTurnId("autonomous"),
+        };
+        this.activeTurnHasAssistantText = false;
+        this.contextUsage.beginTurn();
+        this.notifySubscribers({ type: "turn_started", provider: "claude" });
+        this.syncTurnState("autonomous turn started");
+    }
+    completeAutonomousTurn() {
+        if (!this.autonomousTurn) {
+            return;
+        }
+        this.notifySubscribers({ type: "turn_completed", provider: "claude" });
+        this.autonomousTurn = null;
+        this.activeTurnHasAssistantText = false;
+        this.syncTurnState("autonomous turn completed");
+    }
+    failActiveTurns(errorMessage) {
+        const failure = this.buildTurnFailedEvent(errorMessage);
+        this.flushPendingToolCalls();
+        if (this.activeForegroundTurnId) {
+            this.finishForegroundTurn(failure);
+            return;
+        }
+        if (this.autonomousTurn) {
+            this.dispatchEvents([failure]);
+        }
+    }
+    startQueryPump() {
+        if (this.closed || this.queryPumpPromise) {
+            return;
+        }
+        const pump = this.runQueryPump().catch((error) => {
+            this.logger.trace({
+                agentId: this.agentId,
+                provider: "claude",
+                sessionId: this.claudeSessionId,
+                turnId: this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? undefined,
+                err: error,
+            }, "provider.claude.query_pump.exit_unexpected");
+        });
+        this.queryPumpPromise = pump;
+        void pump.finally(() => {
+            if (this.queryPumpPromise === pump) {
+                this.queryPumpPromise = null;
+            }
+        });
+    }
+    async runQueryPump() {
+        let activeQuery;
+        try {
+            activeQuery = await this.ensureQuery();
+        }
+        catch (error) {
+            this.logger.trace({
+                agentId: this.agentId,
+                provider: "claude",
+                sessionId: this.claudeSessionId,
+                turnId: this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? undefined,
+                err: error,
+            }, "provider.claude.query_pump.init_failed");
+            this.failActiveTurns(error instanceof Error ? error.message : "Claude stream failed");
+            return;
+        }
+        let consecutiveInterruptAbortRecoveries = 0;
+        const logRawMessage = (message) => {
+            this.logger.trace({
+                agentId: this.agentId,
+                provider: "claude",
+                sessionId: this.claudeSessionId,
+                turnId: this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? undefined,
+                messageType: message.type,
+                messageSubtype: "subtype" in message ? message.subtype : undefined,
+                messageUuid: "uuid" in message ? message.uuid : undefined,
+                rawEvent: message,
+            }, "provider.claude.raw_event");
+        };
+        const handlePumpedMessage = async (message) => {
+            logRawMessage(message);
+            consecutiveInterruptAbortRecoveries = 0;
+            if (await this.handleMissingResumedConversation(message, activeQuery)) {
+                return true;
+            }
+            await this.routeSdkMessageFromPump(message);
+            return false;
+        };
+        const drainActiveQuery = async () => {
+            for await (const message of activeQuery) {
+                if (await handlePumpedMessage(message)) {
+                    return true;
+                }
+            }
+            return false;
+        };
+        try {
+            while (!this.closed && this.query === activeQuery) {
+                try {
+                    if (await drainActiveQuery()) {
+                        return;
+                    }
+                    if (!this.closed && this.query === activeQuery) {
+                        this.failActiveTurns("Claude stream ended before terminal result");
+                    }
+                    return;
+                }
+                catch (error) {
+                    if (!this.closed &&
+                        this.query === activeQuery &&
+                        this.shouldRecoverInterruptedQueryAbort(error, consecutiveInterruptAbortRecoveries)) {
+                        consecutiveInterruptAbortRecoveries += 1;
+                        this.logger.debug({ recoveries: consecutiveInterruptAbortRecoveries }, "Recovering Claude query pump after interrupt abort");
+                        continue;
+                    }
+                    if (!this.closed && this.query === activeQuery) {
+                        await this.awaitRecentStderrAfterProcessExit(error);
+                        this.failActiveTurns(error instanceof Error ? error.message : "Claude stream failed");
+                    }
+                    return;
+                }
+            }
+        }
+        finally {
+            if (this.query === activeQuery) {
+                this.query = null;
+                this.input = null;
+            }
+        }
+    }
+    shouldSuppressStaleResult(message) {
+        // Suppress stale results from interrupted requests. The cancel path already
+        // emitted the terminal event; this result is leftover from the killed API
+        // request. Consume the flag on ANY result so it doesn't linger.
+        if (message.type === "result" && this.pendingInterruptAbort) {
+            this.pendingInterruptAbort = false;
+            if (message.subtype !== "success") {
+                this.logger.debug("Suppressing stale non-success result from interrupted request");
+                return true;
+            }
+        }
+        if (message.type === "result" && message.subtype !== "success" && this.isAbortError(message)) {
+            this.logger.debug("Suppressing abort result by content");
+            return true;
+        }
+        return false;
+    }
+    isAssistantishMessage(message) {
+        return (message.type === "assistant" ||
+            message.type === "stream_event" ||
+            message.type === "tool_progress" ||
+            (message.type === "system" && message.subtype === "task_notification"));
+    }
+    async routeSdkMessageFromPump(message) {
+        if (this.shouldSuppressStaleResult(message)) {
+            return;
+        }
+        const isForeground = Boolean(this.activeForegroundTurnId);
+        if (!isForeground && this.isAssistantishMessage(message)) {
+            this.startAutonomousTurn();
+        }
+        if (!isForeground && !this.autonomousTurn && message.type === "result") {
+            return;
+        }
+        const turnId = this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? null;
+        const identifiers = readEventIdentifiers(message);
+        this.rememberTranscriptProgress(message, readTranscriptUuid(message));
+        this.logger.trace({
+            agentId: this.agentId,
+            provider: "claude",
+            sessionId: this.claudeSessionId,
+            turnId: turnId ?? undefined,
+            messageType: message.type,
+            identifiers,
+            rawEvent: message,
+        }, "provider.claude.parsed_event");
+        const events = await this.buildPumpedMessageEvents(message, identifiers.messageId, turnId);
+        if (events.length === 0) {
+            return;
+        }
+        if (this.pendingInterruptAbort &&
+            message.type === "result" &&
+            events.some((event) => event.type === "turn_completed" || event.type === "turn_failed") &&
+            (!this.activeForegroundTurnId || !this.foregroundHasVisibleActivity)) {
+            this.pendingInterruptAbort = false;
+            this.logger.debug("Suppressing stale Claude interrupt terminal result");
+            return;
+        }
+        if (events.some((event) => event.type === "timeline" && event.item.type === "assistant_message")) {
+            this.activeTurnHasAssistantText = true;
+        }
+        if (this.activeForegroundTurnId &&
+            events.some((event) => event.type === "timeline" ||
+                event.type === "permission_requested" ||
+                event.type === "permission_resolved")) {
+            this.foregroundHasVisibleActivity = true;
+        }
+        this.dispatchEvents(events);
+    }
+    async buildPumpedMessageEvents(message, messageIdHint, turnId) {
+        const messageEvents = this.translateMessageToEvents(message, {
+            suppressAssistantText: true,
+            suppressReasoning: true,
+        });
+        const assistantTimelineEvents = readClaudeParentToolUseId(message)
+            ? []
+            : this.timelineAssembler
+                .consume({
+                message,
+                runId: turnId,
+                messageIdHint,
+            })
+                .map((item) => ({
+                type: "timeline",
+                item,
+                provider: "claude",
+            }));
+        return [...messageEvents, ...assistantTimelineEvents];
+    }
+    async handleMissingResumedConversation(message, activeQuery) {
+        const staleResumeError = this.readMissingResumedConversationError(message);
+        if (!staleResumeError) {
+            return false;
+        }
+        this.logger.warn({
+            error: staleResumeError,
+        }, "Claude resumed session no longer exists; invalidating persisted session");
+        this.failActiveTurns(staleResumeError);
+        this.input?.end();
+        await this.awaitWithTimeout(activeQuery.return?.(), "query pump return on missing resumed conversation");
+        if (this.query === activeQuery) {
+            this.query = null;
+            this.input = null;
+        }
+        this.persistence = null;
+        this.persistedHistory = [];
+        this.historyPending = false;
+        this.cachedRuntimeInfo = null;
+        this.queryRestartNeeded = false;
+        this.autonomousTurn = null;
+        this.activeForegroundTurnId = null;
+        this.syncTurnState("missing resumed conversation");
+        return true;
+    }
+    async interruptActiveTurn() {
+        const queryToInterrupt = this.query;
+        if (!queryToInterrupt || typeof queryToInterrupt.interrupt !== "function") {
+            this.logger.trace({
+                agentId: this.agentId,
+                provider: "claude",
+                sessionId: this.claudeSessionId,
+                turnId: this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? undefined,
+            }, "provider.claude.interrupt.no_query");
+            return;
+        }
+        this.pendingInterruptAbort = true;
+        try {
+            await this.awaitWithTimeout(queryToInterrupt.interrupt(), "interruptActiveTurn query.interrupt()");
+        }
+        catch (error) {
+            this.logger.warn({ err: error }, "Failed to interrupt active turn");
+        }
+    }
+    translateMessageToEvents(message, options) {
+        const parentToolUseId = readClaudeParentToolUseId(message);
+        if (parentToolUseId) {
+            return this.sidechainTracker.handleMessage(message, parentToolUseId);
+        }
+        const events = [];
+        if (message.type !== "system") {
+            const sessionCapture = this.captureSessionIdFromMessage(message);
+            if (sessionCapture.notice) {
+                events.push({
+                    type: "timeline",
+                    provider: "claude",
+                    item: sessionCapture.notice,
+                });
+            }
+            if (sessionCapture.threadStartedSessionId) {
+                events.push({
+                    type: "thread_started",
+                    provider: "claude",
+                    sessionId: sessionCapture.threadStartedSessionId,
+                });
+            }
+        }
+        switch (message.type) {
+            case "system":
+                this.appendSystemMessageEvents(message, events);
+                break;
+            case "user":
+                this.appendUserMessageEvents(message, events);
+                break;
+            case "assistant": {
+                const timelineItems = this.mapBlocksToTimeline(message.message.content, {
+                    suppressAssistantText: options?.suppressAssistantText ?? false,
+                    suppressReasoning: options?.suppressReasoning ?? false,
+                });
+                for (const item of timelineItems) {
+                    events.push({ type: "timeline", item, provider: "claude" });
+                }
+                break;
+            }
+            case "stream_event":
+                this.appendStreamEventEvents(message, events, options);
+                break;
+            case "result":
+                this.appendResultEvents(message, events);
+                break;
+            default:
+                break;
+        }
+        return events;
+    }
+    emitSubmittedUserMessage(message, turnId) {
+        const events = [];
+        this.appendUserMessageEvents(message, events);
+        if (events.length === 0) {
+            return;
+        }
+        this.foregroundHasVisibleActivity = true;
+        for (const event of events) {
+            if (event.type === "timeline") {
+                this.notifySubscribers({ ...event, turnId });
+            }
+            else {
+                this.notifySubscribers(event);
+            }
+        }
+    }
+    appendSystemMessageEvents(message, events) {
+        if (message.subtype === "init") {
+            const sessionUpdate = this.handleSystemMessage(message);
+            if (sessionUpdate.notice) {
+                events.push({
+                    type: "timeline",
+                    provider: "claude",
+                    item: sessionUpdate.notice,
+                });
+            }
+            if (sessionUpdate.threadStartedSessionId) {
+                events.push({
+                    type: "thread_started",
+                    provider: "claude",
+                    sessionId: sessionUpdate.threadStartedSessionId,
+                });
+            }
+            return;
+        }
+        if (message.subtype === "status") {
+            const status = toObjectRecord(message)?.status;
+            if (status === "compacting") {
+                this.compacting = true;
+                events.push({
+                    type: "timeline",
+                    item: { type: "compaction", status: "loading" },
+                    provider: "claude",
+                });
+            }
+            return;
+        }
+        if (message.subtype === "compact_boundary") {
+            const compactMetadata = readCompactionMetadata(message);
+            events.push({
+                type: "timeline",
+                item: {
+                    type: "compaction",
+                    status: "completed",
+                    trigger: compactMetadata?.trigger === "manual" ? "manual" : "auto",
+                    preTokens: compactMetadata?.preTokens,
+                },
+                provider: "claude",
+            });
+            events.push(this.contextUsage.buildCompactionUsageEvent(compactMetadata?.postTokens));
+            return;
+        }
+        if (message.subtype === "task_notification") {
+            this.appendTaskNotificationEvents(message, events);
+            return;
+        }
+        if (message.subtype === "task_progress") {
+            return;
+        }
+    }
+    appendTaskNotificationEvents(message, events) {
+        // Expire a tracked background shell when its terminal notification lands.
+        // Runs before the Task-subagent drop below — background shells aren't Task
+        // calls, but feeding here keeps the signal independent of that routing.
+        const lifecycle = extractTaskNotificationLifecycleFromSystemRecord(message);
+        if (lifecycle) {
+            this.backgroundTaskTracker.noteTaskNotification(lifecycle);
+        }
+        // TODO: subagent timelines are best-effort. Subagent task_notifications
+        // arrive without parent_tool_use_id but with tool_use_id pointing at the
+        // the parent's subagent tool call, so they slip past the sidechain router and pollute
+        // the parent timeline. Drop them here; eventually thread them into the
+        // parent tool call's sub_agent log instead.
+        const taskUseId = message.tool_use_id;
+        const cachedTool = taskUseId ? this.toolUseCache.get(taskUseId) : undefined;
+        if (isClaudeSubagentToolName(cachedTool?.name)) {
+            return;
+        }
+        const taskNotificationItem = mapTaskNotificationSystemRecordToToolCall(message);
+        if (taskNotificationItem) {
+            events.push({
+                type: "timeline",
+                item: taskNotificationItem,
+                provider: "claude",
+            });
+        }
+    }
+    appendUserMessageEvents(message, events) {
+        if (isSyntheticUserEntry(message)) {
+            return;
+        }
+        if (this.compacting) {
+            this.compacting = false;
+            return;
+        }
+        const messageId = typeof message.uuid === "string" && message.uuid.length > 0 ? message.uuid : undefined;
+        if (messageId && this.emittedUserMessageIds.has(messageId)) {
+            return;
+        }
+        this.rememberUserMessageId(messageId);
+        this.rememberEmittedUserMessageId(messageId);
+        const content = message.message?.content;
+        // Expire a tracked background shell when its terminal notification arrives
+        // as user-message content (the transcript path Claude Code uses).
+        const backgroundLifecycle = extractTaskNotificationLifecycleFromUserContent({
+            content,
+            messageId,
+        });
+        if (backgroundLifecycle) {
+            this.backgroundTaskTracker.noteTaskNotification(backgroundLifecycle);
+        }
+        const taskNotificationItem = mapTaskNotificationUserContentToToolCall({
+            content,
+            messageId,
+        });
+        if (taskNotificationItem) {
+            events.push({
+                type: "timeline",
+                item: taskNotificationItem,
+                provider: "claude",
+            });
+            return;
+        }
+        if (typeof content === "string" && content.length > 0) {
+            if (!isClaudeTranscriptNoiseText(content)) {
+                events.push({
+                    type: "timeline",
+                    item: {
+                        type: "user_message",
+                        text: content,
+                        ...(messageId ? { messageId } : {}),
+                    },
+                    provider: "claude",
+                });
+            }
+            return;
+        }
+        if (Array.isArray(content)) {
+            this.appendUserContentArrayEvents(content, messageId, events);
+        }
+    }
+    appendUserContentArrayEvents(content, messageId, events) {
+        const timelineItems = this.mapBlocksToTimeline(content, {
+            textMessageType: "user_message",
+        });
+        for (const item of timelineItems) {
+            if (item.type === "user_message" && messageId && !item.messageId) {
+                events.push({
+                    type: "timeline",
+                    item: { ...item, messageId },
+                    provider: "claude",
+                });
+                continue;
+            }
+            events.push({ type: "timeline", item, provider: "claude" });
+        }
+    }
+    appendStreamEventEvents(message, events, options) {
+        const usageUpdatedEvent = this.contextUsage.buildStreamUsageEvent(message.event);
+        if (usageUpdatedEvent) {
+            events.push(usageUpdatedEvent);
+        }
+        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" });
+        }
+    }
+    appendResultEvents(message, events) {
+        const usage = this.convertUsage(message, message.modelUsage);
+        if (message.subtype === "success") {
+            // Built-in slash commands (e.g. /voice, /usage, "Unknown command: …")
+            // run client-side in the Claude CLI with no model turn — output_tokens
+            // is 0 and the user-visible text is carried in `result`. Surface it only
+            // when the turn has not already emitted assistant text so zero-token
+            // accounting from provider gateways does not duplicate streamed output.
+            const resultText = typeof message.result === "string" ? message.result.trim() : "";
+            const outputTokens = message.usage?.output_tokens;
+            if (resultText.length > 0 && outputTokens === 0 && !this.activeTurnHasAssistantText) {
+                events.push({
+                    type: "timeline",
+                    provider: "claude",
+                    item: {
+                        type: "assistant_message",
+                        text: resultText,
+                        messageId: message.uuid,
+                    },
+                });
+            }
+            events.push({ type: "turn_completed", provider: "claude", usage });
+            return;
+        }
+        const errorMessage = "errors" in message && Array.isArray(message.errors) && message.errors.length > 0
+            ? message.errors.join("\n")
+            : "Claude run failed";
+        events.push(this.buildTurnFailedEvent(errorMessage));
+    }
+    createClaudeSessionChangedNotice(oldSessionId, newSessionId) {
+        return {
+            type: "assistant_message",
+            text: `Claude switched to a new session: ${oldSessionId} -> ${newSessionId}`,
+        };
+    }
+    captureSessionIdFromMessage(message) {
+        const msgRecord = toObjectRecord(message) ?? {};
+        const sessionId = extractSessionIdRaw({
+            session_id: msgRecord.session_id,
+            sessionId: msgRecord.sessionId,
+            session: isObjectRecord(msgRecord.session) ? { id: msgRecord.session.id } : null,
+        }).trim();
+        if (!sessionId) {
+            return { threadStartedSessionId: null, notice: null };
+        }
+        if (this.claudeSessionId === null) {
+            this.claudeSessionId = sessionId;
+            this.pendingFreshSessionId = null;
+            this.persistence = null;
+            return { threadStartedSessionId: sessionId, notice: null };
+        }
+        if (this.claudeSessionId === sessionId) {
+            this.pendingFreshSessionId = null;
+            return { threadStartedSessionId: null, notice: null };
+        }
+        const oldSessionId = this.claudeSessionId;
+        // Session ID changed mid-stream (e.g. a hook caused Claude to restart
+        // with a new session). Accept the new ID and continue — the turn should
+        // not be failed just because the underlying subprocess cycled.
+        this.logger.warn({ existingSessionId: this.claudeSessionId, newSessionId: sessionId }, "Claude session ID changed in message; accepting new session");
+        this.claudeSessionId = sessionId;
+        this.pendingFreshSessionId = null;
+        this.persistence = null;
+        return {
+            threadStartedSessionId: sessionId,
+            notice: this.createClaudeSessionChangedNotice(oldSessionId, sessionId),
+        };
+    }
+    handleSystemMessage(message) {
+        if (message.subtype !== "init") {
+            return { threadStartedSessionId: null, notice: null };
+        }
+        const msgRecord = toObjectRecord(message) ?? {};
+        const newSessionId = extractSessionIdRaw({
+            session_id: msgRecord.session_id,
+            sessionId: msgRecord.sessionId,
+            session: isObjectRecord(msgRecord.session) ? { id: msgRecord.session.id } : null,
+        }).trim();
+        if (!newSessionId) {
+            return { threadStartedSessionId: null, notice: null };
+        }
+        const existingSessionId = this.claudeSessionId;
+        let threadStartedSessionId = null;
+        let notice = null;
+        if (existingSessionId === null) {
+            this.claudeSessionId = newSessionId;
+            this.pendingFreshSessionId = null;
+            threadStartedSessionId = newSessionId;
+            this.logger.debug({ sessionId: newSessionId }, "Claude session ID set for the first time");
+        }
+        else if (existingSessionId === newSessionId) {
+            this.pendingFreshSessionId = null;
+            this.logger.debug({ sessionId: newSessionId }, "Claude session ID unchanged (same value)");
+        }
+        else {
+            // Session ID changed in an init message (e.g. a hook restarted Claude
+            // with a new session mid-turn). Accept the new ID and continue.
+            this.logger.warn({ existingSessionId, newSessionId }, "Claude session ID changed in init message; accepting new session");
+            this.claudeSessionId = newSessionId;
+            this.pendingFreshSessionId = null;
+            threadStartedSessionId = newSessionId;
+            notice = this.createClaudeSessionChangedNotice(existingSessionId, newSessionId);
+        }
+        this.availableModes = DEFAULT_MODES;
+        this.currentMode = message.permissionMode;
+        if (this.currentMode !== "plan") {
+            this.planResumeMode = this.currentMode;
+        }
+        this.persistence = null;
+        if (message.model) {
+            const normalizedRuntimeModel = normalizeClaudeRuntimeModelId(message.model);
+            this.logger.debug({ runtimeModel: message.model, normalizedRuntimeModel }, "Captured runtime model from SDK init");
+            if (normalizedRuntimeModel) {
+                this.lastOptionsModel = normalizedRuntimeModel;
+            }
+            else if (!this.lastOptionsModel) {
+                this.lastOptionsModel = this.config.model ?? null;
+            }
+            this.lastRuntimeModel = message.model;
+            this.cachedRuntimeInfo = null;
+        }
+        return { threadStartedSessionId, notice };
+    }
+    readMissingResumedConversationError(message) {
+        if (message.type !== "result" || message.subtype !== "error_during_execution") {
+            return null;
+        }
+        if (!this.claudeSessionId) {
+            return null;
+        }
+        const errors = "errors" in message && Array.isArray(message.errors) ? message.errors : [];
+        for (const entry of errors) {
+            if (typeof entry !== "string") {
+                continue;
+            }
+            const match = entry.match(/^No conversation found with session ID:\s*(.+)$/);
+            if (!match) {
+                continue;
+            }
+            if (match[1]?.trim() === this.claudeSessionId) {
+                return entry.trim();
+            }
+        }
+        return null;
+    }
+    convertUsage(message, modelUsage) {
+        return this.contextUsage.buildResultUsage(message, modelUsage);
+    }
+    enqueueTimeline(item) {
+        this.pushEvent({ type: "timeline", item, provider: "claude" });
+    }
+    flushPendingToolCalls() {
+        for (const [id, entry] of this.toolUseCache) {
+            if (entry.started) {
+                this.pushToolCall(mapClaudeCanceledToolCall({
+                    name: entry.name,
+                    callId: id,
+                    input: entry.input ?? null,
+                    output: null,
+                }));
+            }
+        }
+        this.toolUseCache.clear();
+        this.sidechainTracker.clear();
+        this.backgroundTaskTracker.clear();
+    }
+    pushToolCall(item, target) {
+        if (!item) {
+            return;
+        }
+        if (target) {
+            target.push(item);
+            return;
+        }
+        this.enqueueTimeline(item);
+    }
+    pushEvent(event) {
+        this.notifySubscribers(event);
+    }
+    notifySubscribers(event) {
+        const turnId = this.activeForegroundTurnId ?? this.autonomousTurn?.id;
+        const tagged = turnId ? { ...event, turnId } : event;
+        this.logger.trace({
+            agentId: this.agentId,
+            provider: "claude",
+            sessionId: this.claudeSessionId,
+            turnId: getAgentStreamEventTurnId(tagged),
+            event: tagged,
+        }, "provider.claude.event_emit");
+        for (const callback of this.subscribers) {
+            try {
+                callback(tagged);
+            }
+            catch (error) {
+                this.logger.warn({ err: error }, "Subscriber callback threw");
+            }
+        }
+    }
+    normalizePermissionUpdates(updates) {
+        if (!updates || updates.length === 0) {
+            return undefined;
+        }
+        const normalized = updates.filter(isPermissionUpdate);
+        return normalized.length > 0 ? normalized : undefined;
+    }
+    rejectAllPendingPermissions(error) {
+        for (const [id, pending] of this.pendingPermissions) {
+            pending.cleanup?.();
+            pending.reject(error);
+            this.pendingPermissions.delete(id);
+        }
+    }
+    loadPersistedHistory(sessionId) {
+        try {
+            const historyPath = this.resolveHistoryPath(sessionId);
+            if (!historyPath || !fs.existsSync(historyPath)) {
+                return;
+            }
+            this.ingestPersistedHistory(fs.readFileSync(historyPath, "utf8"));
+        }
+        catch {
+            // ignore history load failures
+        }
+    }
+    ingestPersistedHistory(content) {
+        if (!content) {
+            return;
+        }
+        const timeline = [];
+        for (const line of content.split(/\r?\n/)) {
+            this.ingestPersistedHistoryLine(line, timeline);
+        }
+        if (timeline.length > 0) {
+            this.persistedHistory = [...this.persistedHistory, ...timeline];
+            this.historyPending = true;
+        }
+    }
+    ingestPersistedHistoryLine(line, timeline) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            return;
+        }
+        let entry;
+        try {
+            const parsed = JSON.parse(trimmed);
+            const record = toObjectRecord(parsed);
+            if (!record) {
+                return;
+            }
+            entry = record;
+        }
+        catch {
+            return;
+        }
+        if (entry.isSidechain) {
+            return;
+        }
+        const historyTimestamp = normalizeProviderReplayTimestamp(entry.timestamp);
+        const items = this.convertHistoryEntry(entry);
+        const isVisibleUserEntry = entry.type === "user" &&
+            typeof entry.uuid === "string" &&
+            !isSyntheticHistoryUserEntry(entry) &&
+            !isToolResultUserEntry(entry);
+        if (isVisibleUserEntry && typeof entry.uuid === "string") {
+            this.rememberUserMessageId(entry.uuid);
+            this.rememberRewindUserAnchor(entry.uuid);
+        }
+        if (entry.type === "assistant" && typeof entry.uuid === "string") {
+            this.rememberRewindAssistantAnchor(entry.uuid);
+        }
+        if (items.length > 0) {
+            timeline.push(...items.map((item) => ({
+                item,
+                timestamp: historyTimestamp ?? undefined,
+            })));
+        }
+    }
+    resolveHistoryPath(sessionId) {
+        const cwd = this.config.cwd;
+        if (cwd) {
+            const direct = resolveTranscriptPath({ cwd, sessionId });
+            if (fs.existsSync(direct))
+                return direct;
+        }
+        // The transcript may live under a different project-dir slug than the
+        // current cwd — e.g. the session was created under a now-renamed $HOME
+        // (/Users/marcelo/…) and is resumed from /Users/claudinho/… (or any
+        // fallback cwd). Claude's per-cwd path no longer matches, so scan all
+        // project dirs; without this the resumed chat hydrates empty (blank).
+        return findTranscriptAcrossProjects(sessionId);
+    }
+    convertHistoryEntry(entry) {
+        return convertClaudeHistoryEntry(entry, (content) => this.mapBlocksToTimeline(content));
+    }
+    // Maps Claude content blocks into AgentTimelineItems.
+    //
+    // textMessageType controls what type text blocks emit:
+    //   - "assistant_message" (default): one item per text block (streaming granularity)
+    //   - "user_message": coalesces all text blocks into a single user_message
+    //     (matches extractUserMessageText semantics: trim each block, join with "\n\n")
+    //
+    // suppressAssistantText only applies when textMessageType is "assistant_message" — user text
+    // must never be suppressed since the TimelineAssembler only handles assistant text.
+    //
+    // NOTE: convertClaudeHistoryEntry uses extractUserMessageText directly instead of this function
+    // for user entries. Both paths must produce equivalent user_message items.
+    mapBlocksToTimeline(content, options) {
+        const textMessageType = options?.textMessageType ?? "assistant_message";
+        const suppressText = textMessageType === "assistant_message" && (options?.suppressAssistantText ?? false);
+        const suppressReasoning = options?.suppressReasoning ?? false;
+        if (typeof content === "string") {
+            if (!content ||
+                content === INTERRUPT_TOOL_USE_PLACEHOLDER ||
+                isClaudeTranscriptNoiseText(content)) {
+                return [];
+            }
+            if (suppressText) {
+                return [];
+            }
+            return [{ type: textMessageType, text: content }];
+        }
+        const items = [];
+        // User SDK entries can arrive as multiple text blocks, but Paseo treats them as one message.
+        const userTextParts = [];
+        for (const block of content) {
+            if (!isClaudeContentChunk(block)) {
+                continue;
+            }
+            this.mapBlockToTimeline(block, {
+                items,
+                userTextParts,
+                textMessageType,
+                suppressText,
+                suppressReasoning,
+            });
+        }
+        if (textMessageType === "user_message" && userTextParts.length > 0) {
+            items.unshift({
+                type: "user_message",
+                text: userTextParts.join("\n\n"),
+            });
+        }
+        return items;
+    }
+    appendTextBlockToTimeline(block, context) {
+        const { items, userTextParts, textMessageType, suppressText } = context;
+        const text = typeof block.text === "string" ? block.text : "";
+        if (!text || text === INTERRUPT_TOOL_USE_PLACEHOLDER || isClaudeTranscriptNoiseText(text)) {
+            return;
+        }
+        if (textMessageType === "user_message") {
+            const trimmed = text.trim();
+            if (trimmed) {
+                userTextParts.push(trimmed);
+            }
+            return;
+        }
+        if (!suppressText) {
+            items.push({ type: "assistant_message", text });
+        }
+    }
+    mapBlockToTimeline(block, context) {
+        switch (block.type) {
+            case "text":
+            case "text_delta":
+                this.appendTextBlockToTimeline(block, context);
+                break;
+            case "thinking":
+            case "thinking_delta":
+                if (typeof block.thinking === "string" && block.thinking && !context.suppressReasoning) {
+                    context.items.push({ type: "reasoning", text: block.thinking });
+                }
+                break;
+            case "tool_use":
+            case "server_tool_use":
+            case "mcp_tool_use":
+                this.handleToolUseStart(block, context.items);
+                break;
+            case "tool_result":
+            case "mcp_tool_result":
+            case "web_fetch_tool_result":
+            case "web_search_tool_result":
+            case "code_execution_tool_result":
+            case "bash_code_execution_tool_result":
+            case "text_editor_code_execution_tool_result":
+                this.handleToolResult(block, context.items);
+                break;
+            default:
+                break;
+        }
+    }
+    handleToolUseStart(block, items) {
+        const entry = this.upsertToolUseEntry(block);
+        if (!entry) {
+            return;
+        }
+        if (entry.started) {
+            return;
+        }
+        entry.started = true;
+        this.toolUseCache.set(entry.id, entry);
+        this.pushToolCall(mapClaudeRunningToolCall({
+            name: entry.name,
+            callId: entry.id,
+            input: entry.input ?? this.normalizeToolInput(block.input) ?? null,
+            output: null,
+        }), items);
+    }
+    handleToolResult(block, items) {
+        const entry = typeof block.tool_use_id === "string" ? this.toolUseCache.get(block.tool_use_id) : undefined;
+        const blockToolName = typeof block.tool_name === "string" ? block.tool_name : undefined;
+        const toolName = entry?.name ?? blockToolName ?? "tool";
+        const callId = typeof block.tool_use_id === "string" && block.tool_use_id.length > 0
+            ? block.tool_use_id
+            : (entry?.id ?? null);
+        // Pull image blocks out of the result so base64 never reaches the tool output, and render each
+        // one as an assistant_message markdown image after the tool_call (matching how Codex emits).
+        const { images, text } = splitClaudeToolResultImages(block.content);
+        const output = this.buildToolOutput(text, block, entry);
+        this.trackBackgroundShellStart(block, toolName);
+        if (block.is_error) {
+            this.pushToolCall(mapClaudeFailedToolCall({
+                name: toolName,
+                callId,
+                input: entry?.input ?? null,
+                output: output ?? null,
+                error: { ...block, content: text },
+            }), items);
+        }
+        else {
+            this.pushToolCall(mapClaudeCompletedToolCall({
+                name: toolName,
+                callId,
+                input: entry?.input ?? null,
+                output: output ?? null,
+            }), items);
+        }
+        for (const image of images) {
+            const imageItem = renderProviderImageOutputAsAssistantMarkdown(image, {
+                materialize: materializeProviderImage,
+            });
+            if (imageItem) {
+                items.push(imageItem);
+            }
+        }
+        if (typeof block.tool_use_id === "string") {
+            this.toolUseCache.delete(block.tool_use_id);
+            this.sidechainTracker.delete(block.tool_use_id);
+        }
+    }
+    /**
+     * A backgrounded Bash ("Bash" with run_in_background) returns its handle
+     * immediately — "Command running in background with ID: <id>" — so its
+     * tool_result is the START signal for a shell that will outlive the turn.
+     */
+    trackBackgroundShellStart(block, toolName) {
+        if (toolName !== "Bash" || block.is_error) {
+            return;
+        }
+        const resultText = typeof block.content === "string" ? block.content : JSON.stringify(block.content ?? "");
+        this.backgroundTaskTracker.noteToolResultText(resultText);
+    }
+    buildToolOutput(content, block, entry) {
+        if (block.is_error) {
+            return undefined;
+        }
+        const blockServer = typeof block.server === "string" ? block.server : undefined;
+        const blockToolName = typeof block.tool_name === "string" ? block.tool_name : undefined;
+        const server = entry?.server ?? blockServer ?? "tool";
+        const tool = entry?.name ?? blockToolName ?? "tool";
+        const coercedContent = coerceToolResultContentToString(content);
+        const input = entry?.input;
+        // Build structured result based on tool type
+        const structured = this.buildStructuredToolResult(server, tool, coercedContent, input);
+        if (structured) {
+            return structured;
+        }
+        // Fallback format - try to parse JSON first
+        const result = {};
+        if (coercedContent.length > 0) {
+            try {
+                // If content is a JSON string, parse it
+                result.output = JSON.parse(coercedContent);
+            }
+            catch {
+                // If not JSON, return unchanged (no extra wrapping)
+                result.output = coercedContent;
+            }
+        }
+        // Preserve file changes tracked during tool execution
+        if (entry?.files?.length) {
+            result.files = entry.files;
+        }
+        return Object.keys(result).length > 0 ? result : undefined;
+    }
+    isCommandExecutionTool(normalizedServer, normalizedTool, input) {
+        if (normalizedServer.includes("bash") ||
+            normalizedServer.includes("shell") ||
+            normalizedServer.includes("command")) {
+            return true;
+        }
+        if (normalizedTool.includes("bash") ||
+            normalizedTool.includes("shell") ||
+            normalizedTool.includes("command")) {
+            return true;
+        }
+        return Boolean(input && (typeof input.command === "string" || Array.isArray(input.command)));
+    }
+    static isFileWriteTool(normalizedTool) {
+        return (normalizedTool.includes("write") ||
+            normalizedTool === "write_file" ||
+            normalizedTool === "create_file");
+    }
+    static isFileEditTool(normalizedTool) {
+        return (normalizedTool.includes("edit") ||
+            normalizedTool.includes("patch") ||
+            normalizedTool === "apply_patch" ||
+            normalizedTool === "apply_diff");
+    }
+    static isFileReadTool(normalizedTool) {
+        return (normalizedTool.includes("read") ||
+            normalizedTool === "read_file" ||
+            normalizedTool === "view_file");
+    }
+    buildStructuredToolResult(server, tool, output, input) {
+        const normalizedServer = server.toLowerCase();
+        const normalizedTool = tool.toLowerCase();
+        if (this.isCommandExecutionTool(normalizedServer, normalizedTool, input)) {
+            const command = this.extractCommandText(input ?? {}) ?? "command";
+            return {
+                type: "command",
+                command,
+                output,
+                cwd: typeof input?.cwd === "string" ? input.cwd : undefined,
+            };
+        }
+        if (ClaudeAgentSession.isFileWriteTool(normalizedTool) &&
+            input &&
+            typeof input.file_path === "string") {
+            return {
+                type: "file_write",
+                filePath: input.file_path,
+                oldContent: "",
+                newContent: typeof input.content === "string" ? input.content : output,
+            };
+        }
+        if (ClaudeAgentSession.isFileEditTool(normalizedTool) &&
+            input &&
+            typeof input.file_path === "string") {
+            // Support both old_str/new_str and old_string/new_string parameter names
+            const oldContent = firstStringField(input, "old_str", "old_string");
+            const newContent = firstStringField(input, "new_str", "new_string");
+            const diff = firstStringField(input, "patch", "diff");
+            return {
+                type: "file_edit",
+                filePath: input.file_path,
+                diff,
+                oldContent,
+                newContent,
+            };
+        }
+        if (ClaudeAgentSession.isFileReadTool(normalizedTool) &&
+            input &&
+            typeof input.file_path === "string") {
+            return {
+                type: "file_read",
+                filePath: input.file_path,
+                content: output,
+            };
+        }
+        return undefined;
+    }
+    updatePartialEventToolState(event) {
+        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") {
+                this.toolUseIndexToId.set(event.index, block.id);
+                this.toolUseInputBuffers.delete(block.id);
+            }
+            return false;
+        }
+        if (event.type === "content_block_delta") {
+            const delta = isClaudeContentChunk(event.delta) ? event.delta : null;
+            if (delta?.type === "input_json_delta") {
+                const partialJson = typeof delta.partial_json === "string" ? delta.partial_json : undefined;
+                this.handleToolInputDelta(event.index, partialJson);
+                return true;
+            }
+            return false;
+        }
+        if (event.type === "content_block_stop" && typeof event.index === "number") {
+            const toolId = this.toolUseIndexToId.get(event.index);
+            if (toolId) {
+                this.toolUseIndexToId.delete(event.index);
+                this.toolUseInputBuffers.delete(toolId);
+            }
+        }
+        return false;
+    }
+    mapPartialEvent(event, options) {
+        if (this.updatePartialEventToolState(event)) {
+            return [];
+        }
+        switch (event.type) {
+            case "content_block_start":
+                return isClaudeContentChunk(event.content_block)
+                    ? this.mapBlocksToTimeline([event.content_block], {
+                        suppressAssistantText: options?.suppressAssistantText,
+                        suppressReasoning: options?.suppressReasoning,
+                    })
+                    : [];
+            case "content_block_delta":
+                return isClaudeContentChunk(event.delta)
+                    ? this.mapBlocksToTimeline([event.delta], {
+                        suppressAssistantText: options?.suppressAssistantText,
+                        suppressReasoning: options?.suppressReasoning,
+                    })
+                    : [];
+            default:
+                return [];
+        }
+    }
+    upsertToolUseEntry(block) {
+        const id = typeof block.id === "string" ? block.id : undefined;
+        if (!id) {
+            return null;
+        }
+        const existing = this.toolUseCache.get(id) ?? createDefaultToolUseCacheEntry(id, block);
+        if (typeof block.name === "string" && block.name.length > 0) {
+            existing.name = block.name;
+        }
+        if (typeof block.server === "string" && block.server.length > 0) {
+            existing.server = block.server;
+        }
+        else if (!existing.server) {
+            existing.server = existing.name;
+        }
+        if (block.type === "tool_use" ||
+            block.type === "mcp_tool_use" ||
+            block.type === "server_tool_use") {
+            const input = this.normalizeToolInput(block.input);
+            if (input) {
+                this.applyToolInput(existing, input);
+            }
+        }
+        this.toolUseCache.set(id, existing);
+        return existing;
+    }
+    handleToolInputDelta(index, partialJson) {
+        if (typeof index !== "number" || typeof partialJson !== "string") {
+            return;
+        }
+        const toolId = this.toolUseIndexToId.get(index);
+        if (!toolId) {
+            return;
+        }
+        const buffer = (this.toolUseInputBuffers.get(toolId) ?? "") + partialJson;
+        this.toolUseInputBuffers.set(toolId, buffer);
+        const entry = this.toolUseCache.get(toolId);
+        const parsed = parsePartialJsonObject(buffer);
+        if (!entry || !parsed) {
+            return;
+        }
+        const normalized = this.normalizeToolInput(parsed.value);
+        if (!normalized) {
+            return;
+        }
+        if (!parsed.complete && Object.keys(normalized).length === 0) {
+            return;
+        }
+        if (this.areToolInputsEqual(entry.input ?? undefined, normalized)) {
+            return;
+        }
+        this.applyToolInput(entry, normalized);
+        this.toolUseCache.set(toolId, entry);
+        this.pushToolCall(mapClaudeRunningToolCall({
+            name: entry.name,
+            callId: toolId,
+            input: normalized,
+            output: null,
+        }));
+    }
+    normalizeToolInput(input) {
+        if (!isMetadata(input)) {
+            return null;
+        }
+        return input;
+    }
+    areToolInputsEqual(left, right) {
+        if (!left) {
+            return false;
+        }
+        const leftKeys = Object.keys(left);
+        const rightKeys = Object.keys(right);
+        if (leftKeys.length !== rightKeys.length) {
+            return false;
+        }
+        return rightKeys.every((key) => left[key] === right[key]);
+    }
+    applyToolInput(entry, input) {
+        entry.input = input;
+        if (this.isCommandTool(entry.name, input)) {
+            entry.classification = "command";
+            entry.commandText = this.extractCommandText(input) ?? entry.commandText;
+        }
+        else {
+            const files = this.extractFileChanges(input);
+            if (files?.length) {
+                entry.classification = "file_change";
+                entry.files = files;
+            }
+        }
+    }
+    isCommandTool(name, input) {
+        const normalized = name.toLowerCase();
+        if (normalized.includes("bash") ||
+            normalized.includes("shell") ||
+            normalized.includes("terminal") ||
+            normalized.includes("command")) {
+            return true;
+        }
+        if (typeof input.command === "string" || Array.isArray(input.command)) {
+            return true;
+        }
+        return false;
+    }
+    extractCommandText(input) {
+        const command = input.command;
+        if (typeof command === "string" && command.length > 0) {
+            return command;
+        }
+        if (Array.isArray(command)) {
+            const tokens = command.filter((value) => typeof value === "string");
+            if (tokens.length > 0) {
+                return tokens.join(" ");
+            }
+        }
+        if (typeof input.description === "string" && input.description.length > 0) {
+            return input.description;
+        }
+        return undefined;
+    }
+    extractFileChanges(input) {
+        if (typeof input.file_path === "string" && input.file_path.length > 0) {
+            const relative = this.relativizePath(input.file_path);
+            if (relative) {
+                return [{ path: relative, kind: this.detectFileKind(input.file_path) }];
+            }
+        }
+        if (typeof input.patch === "string" && input.patch.length > 0) {
+            const files = this.parsePatchFileList(input.patch);
+            if (files.length > 0) {
+                return files.map((entry) => ({
+                    path: this.relativizePath(entry.path) ?? entry.path,
+                    kind: entry.kind,
+                }));
+            }
+        }
+        if (Array.isArray(input.files)) {
+            const files = [];
+            for (const value of input.files) {
+                if (typeof value === "string" && value.length > 0) {
+                    files.push({
+                        path: this.relativizePath(value) ?? value,
+                        kind: this.detectFileKind(value),
+                    });
+                }
+            }
+            if (files.length > 0) {
+                return files;
+            }
+        }
+        return undefined;
+    }
+    detectFileKind(filePath) {
+        try {
+            return fs.existsSync(filePath) ? "update" : "add";
+        }
+        catch {
+            return "update";
+        }
+    }
+    relativizePath(target) {
+        if (!target) {
+            return undefined;
+        }
+        const cwd = this.config.cwd;
+        if (cwd && target.startsWith(cwd)) {
+            const relative = path.relative(cwd, target);
+            return relative.length > 0 ? relative : path.basename(target);
+        }
+        return target;
+    }
+    parsePatchFileList(patch) {
+        const files = [];
+        const seen = new Set();
+        for (const line of patch.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            let kind = null;
+            let parsedPath = null;
+            if (trimmed.startsWith("*** Add File:")) {
+                kind = "add";
+                parsedPath = trimmed.replace("*** Add File:", "").trim();
+            }
+            else if (trimmed.startsWith("*** Delete File:")) {
+                kind = "delete";
+                parsedPath = trimmed.replace("*** Delete File:", "").trim();
+            }
+            else if (trimmed.startsWith("*** Update File:")) {
+                kind = "update";
+                parsedPath = trimmed.replace("*** Update File:", "").trim();
+            }
+            if (kind && parsedPath && !seen.has(`${kind}:${parsedPath}`)) {
+                seen.add(`${kind}:${parsedPath}`);
+                files.push({ path: parsedPath, kind });
+            }
+        }
+        return files;
+    }
+}
+function hasToolLikeBlock(block) {
+    if (!block || typeof block !== "object") {
+        return false;
+    }
+    const type = typeof block.type === "string" ? block.type.toLowerCase() : "";
+    return type.includes("tool");
+}
+function readCompactionMetadata(source) {
+    const sourceRecord = toObjectRecord(source);
+    if (!sourceRecord) {
+        return null;
+    }
+    const candidates = [
+        sourceRecord.compact_metadata,
+        sourceRecord.compactMetadata,
+        sourceRecord.compactionMetadata,
+    ];
+    for (const candidate of candidates) {
+        const metadata = toObjectRecord(candidate);
+        if (!metadata) {
+            continue;
+        }
+        const trigger = typeof metadata.trigger === "string" ? metadata.trigger : undefined;
+        const preTokensRaw = metadata.preTokens ?? metadata.pre_tokens;
+        const preTokens = typeof preTokensRaw === "number" ? preTokensRaw : undefined;
+        const postTokensRaw = metadata.postTokens ?? metadata.post_tokens;
+        const postTokens = typeof postTokensRaw === "number" ? postTokensRaw : undefined;
+        return { trigger, preTokens, postTokens };
+    }
+    return null;
+}
+function normalizeHistoryBlocks(content) {
+    if (Array.isArray(content)) {
+        const blocks = content.filter((entry) => isClaudeContentChunk(entry));
+        return blocks.length > 0 ? blocks : null;
+    }
+    if (isClaudeContentChunk(content)) {
+        return [content];
+    }
+    return null;
+}
+function mapAssistantHistoryBlocksWithMessageId(entry, content, mapBlocks) {
+    const items = mapBlocks(content);
+    const assistantMessageId = typeof entry.uuid === "string" && entry.uuid.length > 0 ? entry.uuid : null;
+    if (!assistantMessageId) {
+        return items;
+    }
+    for (const item of items) {
+        if (item.type === "assistant_message" && !item.messageId) {
+            item.messageId = assistantMessageId;
+        }
+    }
+    return items;
+}
+function convertClaudeHistoryEntryPreamble(entry) {
+    if (entry.type === "system" && entry.subtype === "compact_boundary") {
+        const compactMetadata = readCompactionMetadata(entry);
+        return {
+            shortCircuit: [
+                {
+                    type: "compaction",
+                    status: "completed",
+                    trigger: compactMetadata?.trigger === "manual" ? "manual" : "auto",
+                    preTokens: compactMetadata?.preTokens,
+                },
+            ],
+        };
+    }
+    const taskNotificationItem = mapTaskNotificationSystemRecordToToolCall(entry);
+    if (taskNotificationItem) {
+        return { shortCircuit: [taskNotificationItem] };
+    }
+    if (entry.isCompactSummary) {
+        return { shortCircuit: [] };
+    }
+    if (entry.type === "user" && isSyntheticHistoryUserEntry(entry)) {
+        return { shortCircuit: [] };
+    }
+    const message = entry?.message;
+    if (!message || !("content" in message)) {
+        return { shortCircuit: [] };
+    }
+    const content = message.content;
+    if ((entry.type === "user" || entry.type === "assistant") &&
+        isClaudeTranscriptNoiseContent(content)) {
+        return { shortCircuit: [] };
+    }
+    return { proceed: { content } };
+}
+function isProviderImageMessage(item) {
+    return item.type === "assistant_message" && isProviderImageMarkdown(item.text);
+}
+export function convertClaudeHistoryEntry(entry, mapBlocks) {
+    const preamble = convertClaudeHistoryEntryPreamble(entry);
+    if ("shortCircuit" in preamble) {
+        return preamble.shortCircuit;
+    }
+    const { content } = preamble.proceed;
+    const normalizedBlocks = normalizeHistoryBlocks(content);
+    const contentValue = typeof content === "string" ? 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 userTaskNotificationItem = mapTaskNotificationUserContentToToolCall({
+            content,
+            messageId: userMessageId,
+        });
+        if (userTaskNotificationItem) {
+            return [userTaskNotificationItem];
+        }
+    }
+    const timeline = [];
+    if (entry.type === "user") {
+        const text = extractUserMessageText(content);
+        if (text) {
+            timeline.push({
+                type: "user_message",
+                text,
+                ...(userMessageId ? { messageId: userMessageId } : {}),
+            });
+        }
+    }
+    if (hasToolBlock && normalizedBlocks) {
+        const mapped = mapBlocks(normalizedBlocks);
+        if (entry.type === "user") {
+            // tool_result handling (handleToolResult) emits image markdown as an assistant_message
+            // alongside the tool_call. User-entry text blocks also map to assistant_message in this path
+            // and must stay suppressed, so keep tool_calls plus only the image assistant_messages.
+            const toolItems = mapped.filter((item) => item.type === "tool_call" || isProviderImageMessage(item));
+            return timeline.length ? [...timeline, ...toolItems] : toolItems;
+        }
+        return mapped;
+    }
+    if (entry.type === "assistant" && contentValue) {
+        return mapAssistantHistoryBlocksWithMessageId(entry, contentValue, mapBlocks);
+    }
+    return timeline;
+}
+function createAsyncMessageInput() {
+    const queue = [];
+    const resolvers = [];
+    let closed = false;
+    return {
+        push(item) {
+            if (closed) {
+                return;
+            }
+            const resolve = resolvers.shift();
+            if (resolve) {
+                resolve({ value: item, done: false });
+                return;
+            }
+            queue.push(item);
+        },
+        end() {
+            closed = true;
+            while (resolvers.length > 0) {
+                const resolve = resolvers.shift();
+                resolve?.({ value: undefined, done: true });
+            }
+        },
+        iterable: {
+            [Symbol.asyncIterator]() {
+                return {
+                    next: () => {
+                        if (queue.length > 0) {
+                            const value = queue.shift();
+                            if (value !== undefined) {
+                                return Promise.resolve({ value, done: false });
+                            }
+                        }
+                        if (closed) {
+                            return Promise.resolve({ value: undefined, done: true });
+                        }
+                        return new Promise((resolve) => {
+                            resolvers.push(resolve);
+                        });
+                    },
+                };
+            },
+        },
+    };
+}
+async function pathExists(target) {
+    try {
+        await fsPromises.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function collectRecentClaudeSessions(root, limit) {
+    let projectDirs;
+    try {
+        projectDirs = await fsPromises.readdir(root);
+    }
+    catch {
+        return [];
+    }
+    const projectFileLists = await Promise.all(projectDirs.map(async (dirName) => {
+        const projectPath = path.join(root, dirName);
+        try {
+            const stats = await fsPromises.stat(projectPath);
+            if (!stats.isDirectory())
+                return { projectPath, files: [] };
+            const files = await fsPromises.readdir(projectPath);
+            return { projectPath, files };
+        }
+        catch {
+            return { projectPath, files: [] };
+        }
+    }));
+    const fileEntries = projectFileLists.flatMap(({ projectPath, files }) => files.filter((f) => f.endsWith(".jsonl")).map((f) => path.join(projectPath, f)));
+    const statResults = await Promise.all(fileEntries.map(async (fullPath) => {
+        try {
+            const fileStats = await fsPromises.stat(fullPath);
+            return { path: fullPath, mtime: fileStats.mtime };
+        }
+        catch {
+            return null;
+        }
+    }));
+    const candidates = statResults.filter((entry) => entry !== null);
+    return candidates.sort((a, b) => b.mtime.getTime() - a.mtime.getTime()).slice(0, limit);
+}
+function isFinishedAccumulator(acc) {
+    return Boolean(acc.sessionId && acc.cwd && acc.title);
+}
+function applyClaudeSessionEntryToAccumulator(entryRaw, acc) {
+    const entry = toObjectRecord(entryRaw);
+    if (!entry) {
+        return;
+    }
+    if (entry.isSidechain) {
+        return;
+    }
+    if (entry.type === "user" && isSyntheticUserEntry(entry)) {
+        return;
+    }
+    if (!acc.sessionId && typeof entry.sessionId === "string") {
+        acc.sessionId = entry.sessionId;
+    }
+    if (!acc.cwd && typeof entry.cwd === "string") {
+        acc.cwd = entry.cwd;
+    }
+    if (entry.type === "user" && entry.message) {
+        const text = extractClaudeUserText(entry.message);
+        if (text) {
+            if (!acc.title) {
+                acc.title = text;
+            }
+            const preview = normalizeImportablePromptPreview(text);
+            acc.firstPromptPreview ?? (acc.firstPromptPreview = preview);
+            acc.lastPromptPreview = preview;
+        }
+        return;
+    }
+}
+async function parseClaudeSessionDescriptor(filePath, mtime) {
+    let content;
+    try {
+        content = await fsPromises.readFile(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const acc = {
+        sessionId: null,
+        cwd: null,
+        title: null,
+        firstPromptPreview: null,
+        lastPromptPreview: null,
+    };
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        applyClaudeSessionEntryToAccumulator(entry, acc);
+        if (isFinishedAccumulator(acc)) {
+            break;
+        }
+    }
+    const { sessionId, cwd, title } = acc;
+    if (!sessionId || !cwd) {
+        return null;
+    }
+    return {
+        providerHandleId: sessionId,
+        cwd,
+        title: (title ?? "").trim() || `Claude session ${sessionId.slice(0, 8)}`,
+        firstPromptPreview: acc.firstPromptPreview,
+        lastPromptPreview: acc.lastPromptPreview,
+        lastActivityAt: mtime,
+    };
+}
+function normalizeImportablePromptPreview(text) {
+    const normalized = text.trim().replace(/\s+/g, " ");
+    if (!normalized)
+        return null;
+    return normalized.length > 160 ? normalized.slice(0, 160) : normalized;
+}
+function normalizeClaudeUserPromptText(text) {
+    const normalized = text.trim();
+    if (!CLAUDE_COMMAND_MESSAGE_PATTERN.test(normalized)) {
+        return normalized || null;
+    }
+    const command = readClaudeCommandPromptName(normalized);
+    if (!command) {
+        return null;
+    }
+    const commandArgs = normalized.match(CLAUDE_COMMAND_ARGS_PATTERN)?.[1]?.trim();
+    if (commandArgs) {
+        return `${command} ${commandArgs}`;
+    }
+    return command;
+}
+function readClaudeCommandPromptName(text) {
+    const commandName = text.match(CLAUDE_COMMAND_NAME_PATTERN)?.[1]?.trim();
+    if (commandName) {
+        return commandName.startsWith("/") ? commandName : `/${commandName}`;
+    }
+    const commandMessage = text.match(CLAUDE_COMMAND_MESSAGE_PATTERN)?.[1]?.trim();
+    if (!commandMessage) {
+        return null;
+    }
+    return commandMessage.startsWith("/") ? commandMessage : `/${commandMessage}`;
+}
+function extractClaudeUserText(messageRaw) {
+    const message = toObjectRecord(messageRaw);
+    if (!message) {
+        return null;
+    }
+    if (typeof message.content === "string") {
+        const normalized = message.content.trim();
+        if (!normalized || isClaudeTranscriptNoiseText(normalized))
+            return null;
+        return normalizeClaudeUserPromptText(normalized);
+    }
+    if (typeof message.text === "string") {
+        const normalized = message.text.trim();
+        if (!normalized || isClaudeTranscriptNoiseText(normalized))
+            return null;
+        return normalizeClaudeUserPromptText(normalized);
+    }
+    if (isUnknownArray(message.content)) {
+        for (const block of message.content) {
+            const blockRecord = toObjectRecord(block);
+            if (blockRecord && typeof blockRecord.text === "string") {
+                const normalized = blockRecord.text.trim();
+                if (normalized && !isClaudeTranscriptNoiseText(normalized)) {
+                    return normalizeClaudeUserPromptText(normalized);
+                }
+            }
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=agent.js.map