pikiloop 0.4.0

package/dist/agent/drivers/claude.js

@@ -0,0 +1,2689 @@
+/**
+ * Claude Code CLI driver: stream parsing, session reads, model listing, usage.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync, spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { registerDriver } from '../driver.js';
+import { 
+// shared helpers
+Q, run, agentError, agentLog, agentWarn, buildStreamPreviewMeta, computeContext, pushRecentActivity, summarizeClaudeToolUse, summarizeClaudeToolResult, joinErrorMessages, parseTodoWriteAsPlan, previewToolCallInput, previewToolCallResult, detectClaudeApiError, isRetryableClaudeApiError, detectClaudeModelError, claudeModelErrorMessage, emitSessionIdUpdate, IMAGE_EXTS, mimeForExt, listPikiloopSessions, mergeManagedAndNativeSessions, readTailLines, stripInjectedPrompts, sanitizeSessionUserPreviewText, SESSION_PREVIEW_IMAGE_PLACEHOLDER_RE, CLAUDE_AT_MENTION_IMAGE_RE, extractClaudeAtMentionImagePaths, attachAgentImage, applyTurnWindow, shortValue, roundPercent, modelFamily, normalizeClaudeModelId, emptyUsage, normalizeUsageStatus, collapseSkillPrompt, } from '../index.js';
+import { AGENT_STREAM_HARD_KILL_GRACE_MS, AGENT_GRACEFUL_ABORT_GRACE_MS, SESSION_RUNNING_THRESHOLD_MS } from '../../core/constants.js';
+import { terminateProcessTree } from '../../core/process-control.js';
+import { getHome, IS_MAC, encodePathAsDirName } from '../../core/platform.js';
+// ---------------------------------------------------------------------------
+// Multimodal stdin
+// ---------------------------------------------------------------------------
+function buildClaudeUserMessage(prompt, attachments) {
+    const content = [];
+    for (const filePath of attachments) {
+        const ext = path.extname(filePath).toLowerCase();
+        if (IMAGE_EXTS.has(ext)) {
+            try {
+                const data = fs.readFileSync(filePath);
+                content.push({
+                    type: 'image',
+                    source: { type: 'base64', media_type: mimeForExt(ext), data: data.toString('base64') },
+                });
+            }
+            catch (e) {
+                agentWarn(`[attach] failed to read image ${filePath}: ${e.message}`);
+            }
+        }
+        else {
+            content.push({ type: 'text', text: `[Attached file: ${filePath}]` });
+        }
+    }
+    content.push({ type: 'text', text: prompt });
+    return JSON.stringify({ type: 'user', message: { role: 'user', content } }) + '\n';
+}
+function claudeUsesStreamJsonInput(o) {
+    return !!o.attachments?.length || !!o.onSteerReady;
+}
+const CLAUDE_STEER_IDLE_CLOSE_MS = 1200;
+/**
+ * Effort + multi-agent-Workflow gate args, shared by BOTH Claude spawn paths
+ * (`claude -p` in claudeCmd below and the PTY/TUI driver in claude-tui.ts).
+ * Kept in one place so the gate can never drift between them — the omission
+ * that once left the Workflow tool always-on under the TUI driver.
+ *
+ * "ultra" is a synthetic picker rung (max depth + Workflow orchestration), never
+ * a real --effort value — translate it to `max` so a stray "ultra" can't reach
+ * and break the CLI, and treat it as an implicit workflow opt-in. The Workflow
+ * tool ships in the default toolset and triggers on a bare "workflow" keyword;
+ * under the bypassPermissions mode pikiloop runs by default that could auto-spawn
+ * a fleet of sub-agents, so drop it entirely unless orchestration was explicitly
+ * enabled (the workflow flag or the "ultra" rung).
+ */
+export function claudeEffortAndWorkflowArgs(o) {
+    const args = [];
+    const ultraEffort = o.thinkingEffort === 'ultra';
+    if (o.thinkingEffort)
+        args.push('--effort', ultraEffort ? 'max' : o.thinkingEffort);
+    if (!o.claudeWorkflowEnabled && !ultraEffort)
+        args.push('--disallowed-tools', 'Workflow');
+    return args;
+}
+/**
+ * Env keys the claude CLI exports to its own subprocesses (Bash tool, hooks)
+ * to mark them as children of a running session. If pikiloop itself was
+ * launched from inside a Claude Code session — agent-driven `npm run dev`
+ * restarts, `! npx pikiloop` typed into the TUI, the self-bootstrap path —
+ * these leak into the daemon's environment and every claude it spawns
+ * inherits them. A claude started with `CLAUDE_CODE_CHILD_SESSION` set runs
+ * in child-session mode: it mirrors transcript persistence to its (absent)
+ * SDK parent instead of writing `~/.claude/projects/<dir>/<id>.jsonl`.
+ * The TUI driver tails that JSONL as its only text source, so a contaminated
+ * spawn streams nothing, returns "(no textual response)", and loses the whole
+ * turn on SIGTERM. Verified on 2.1.173: with these vars set the transcript
+ * never grows past the ai-title line; with them scrubbed every event lands
+ * 0.2–1.2s after it happens.
+ *
+ * Deliberately a closed list: config-style vars users set on purpose
+ * (CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_MAX_OUTPUT_TOKENS, …) must survive.
+ * Shared by both spawn paths (`claude -p` here and the PTY/TUI driver).
+ */
+const CLAUDE_SESSION_CONTEXT_ENV_KEYS = [
+    'CLAUDECODE',
+    'CLAUDE_CODE_CHILD_SESSION',
+    'CLAUDE_CODE_ENTRYPOINT',
+    'CLAUDE_CODE_EXECPATH',
+    'CLAUDE_CODE_SESSION_ID',
+    'CLAUDE_CODE_SSE_PORT',
+    'CLAUDE_EFFORT',
+    'CLAUDE_PERMISSION_MODE',
+];
+export function scrubClaudeSessionContextEnv(env) {
+    for (const key of CLAUDE_SESSION_CONTEXT_ENV_KEYS)
+        delete env[key];
+}
+// ---------------------------------------------------------------------------
+// Command & parser
+// ---------------------------------------------------------------------------
+function claudeCmd(o) {
+    const args = ['claude', '-p', '--verbose', '--output-format', 'stream-json', '--include-partial-messages'];
+    const model = normalizeClaudeModelId(o.claudeModel);
+    if (model)
+        args.push('--model', model);
+    if (o.claudePermissionMode)
+        args.push('--permission-mode', o.claudePermissionMode);
+    // Fork: branch off the parent's full history into a fresh sessionId. The
+    // claude CLI exposes this via `--resume <parent> --fork-session`; the new
+    // session inherits the parent's transcript and gets its own JSONL file.
+    // We record `forkedAtTurn` as lineage metadata only — the agent's actual
+    // context is the full parent history.
+    if (o.forkOf) {
+        args.push('--resume', o.forkOf.parentSessionId, '--fork-session');
+    }
+    else if (o.sessionId) {
+        args.push('--resume', o.sessionId);
+    }
+    if (claudeUsesStreamJsonInput(o)) {
+        args.push('--input-format', 'stream-json');
+        if (o.onSteerReady)
+            args.push('--replay-user-messages');
+        if (o.attachments?.length)
+            o._stdinOverride = buildClaudeUserMessage(o.prompt, o.attachments);
+    }
+    // Effort + Workflow gate — shared with the TUI driver (claude-tui.ts) so the
+    // two spawn paths can never drift. See claudeEffortAndWorkflowArgs.
+    args.push(...claudeEffortAndWorkflowArgs(o));
+    if (o.claudeAppendSystemPrompt)
+        args.push('--append-system-prompt', o.claudeAppendSystemPrompt);
+    if (o.mcpConfigPath)
+        args.push('--mcp-config', o.mcpConfigPath);
+    if (o.claudeExtraArgs?.length)
+        args.push(...o.claudeExtraArgs);
+    return args;
+}
+/**
+ * Route a JSONL event that belongs to a sub-agent (parent_tool_use_id is set).
+ * The event is owned by the Task tool_use whose id matches `parentToolUseId`;
+ * we accumulate the sub-agent's model and tool calls without ever touching
+ * `s.recentActivity` or `s.text` (those stay scoped to the parent agent).
+ */
+function routeClaudeSubAgentEvent(ev, t, parentToolUseId, s) {
+    const sub = s.subAgents.get(parentToolUseId);
+    if (!sub)
+        return; // Task tool_use should always precede sub-agent events; ignore stragglers.
+    if (t === 'system' || t === 'assistant') {
+        const model = ev.model ?? ev.message?.model;
+        if (typeof model === 'string' && model.trim())
+            sub.model = model;
+    }
+    if (t === 'assistant') {
+        const contents = ev.message?.content || [];
+        for (const block of contents) {
+            if (block?.type !== 'tool_use')
+                continue;
+            const toolId = String(block?.id || '').trim();
+            if (!toolId || s.seenClaudeToolIds.has(toolId))
+                continue;
+            const toolName = String(block?.name || 'Tool').trim() || 'Tool';
+            const summary = toolName === 'TodoWrite' ? 'Update plan' : summarizeClaudeToolUse(block?.name, block?.input || {});
+            s.seenClaudeToolIds.add(toolId);
+            s.claudeToolsById.set(toolId, { name: toolName, summary });
+            sub.tools.push({ id: toolId, name: toolName, summary });
+        }
+    }
+}
+function buildClaudeTurnUsage(u, turnOutput) {
+    if (u.input == null && u.output == null && u.cacheRead == null && u.cacheCreation == null)
+        return null;
+    const ctxWindow = claudeEffectiveContextWindow(claudeContextWindowFromModel(u.model));
+    const used = claudeContextUsedFromUsage({
+        input: u.input, cached: u.cacheRead, cacheCreation: u.cacheCreation, output: u.output,
+    });
+    const contextPercent = ctxWindow && used > 0
+        ? Math.min(99.9, Math.round(used / ctxWindow * 1000) / 10)
+        : null;
+    const meta = {
+        inputTokens: u.input,
+        outputTokens: u.output,
+        cachedInputTokens: u.cacheRead,
+        contextUsedTokens: used > 0 ? used : null,
+        contextPercent,
+    };
+    if (turnOutput && turnOutput > 0)
+        meta.turnOutputTokens = turnOutput;
+    return meta;
+}
+/** Hard cap beyond which a native Claude session is treated as idle regardless
+ *  of the last JSONL event — guards against sessions abandoned mid-turn (Ctrl-C
+ *  during a tool call, terminal crash) so they don't stick on "running". */
+const CLAUDE_NATIVE_RUNNING_HARD_CAP_MS = 5 * 60 * 1000;
+const CLAUDE_TURN_TERMINAL_STOP_REASONS = new Set(['end_turn', 'stop_sequence', 'max_tokens', 'refusal']);
+/** Inspect a native Claude JSONL to decide whether a turn is currently in
+ *  progress. Pure-mtime detection misses cases where Claude is mid-tool-use and
+ *  hasn't appended for >10s; this checks the trailing event for a non-terminal
+ *  state (user message awaiting reply, or assistant message with a non-end stop
+ *  reason like `tool_use`). */
+function isClaudeNativeSessionRunning(filePath, mtimeMs) {
+    const age = Date.now() - mtimeMs;
+    if (age < SESSION_RUNNING_THRESHOLD_MS)
+        return true;
+    if (age > CLAUDE_NATIVE_RUNNING_HARD_CAP_MS)
+        return false;
+    const tailLines = readTailLines(filePath, 64 * 1024);
+    for (let i = tailLines.length - 1; i >= 0; i--) {
+        const line = tailLines[i];
+        if (!line || line[0] !== '{')
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const t = ev?.type;
+        // Skip auto-title events — they fire after a turn completes and are not a liveness signal.
+        if (t === 'ai-title' || t === 'system')
+            continue;
+        if (t === 'user')
+            return true;
+        if (t === 'assistant') {
+            const stop = ev?.message?.stop_reason;
+            return stop != null ? !CLAUDE_TURN_TERMINAL_STOP_REASONS.has(stop) : true;
+        }
+        // Unknown event type — be conservative.
+        return false;
+    }
+    return false;
+}
+export function claudeContextWindowFromModel(model) {
+    const id = normalizeClaudeModelId(model).toLowerCase();
+    if (!id)
+        return null;
+    if (id === 'haiku' || /^claude-haiku-/.test(id))
+        return 200_000;
+    if (id === 'opus' || id === 'sonnet' || id === 'fable')
+        return 1_000_000;
+    if (/^claude-(opus|sonnet)-/.test(id) || /^claude-fable-/.test(id))
+        return 1_000_000;
+    return null;
+}
+// Mirrors Claude Code 2.1.112's `Yn()` + `v38()` denominator (and `pj()` display
+// formula) — verified by extracting cli.js from the last JS-source release.
+//   uDY = 20_000  // max output reservation cap
+//   t_7 = 13_000  // auto-compact buffer
+// Effective denominator with autoCompact enabled (cc's default) is
+// `window - 20K - 13K`. Without these subtractions the percent we display
+// drifts from the number cc itself reports (e.g. Opus 1M shows the user
+// `Context left until auto-compact: X%` against a 967_000 denominator, not
+// against a flat 1_000_000).
+const CLAUDE_MAX_OUTPUT_RESERVE = 20_000;
+const CLAUDE_AUTOCOMPACT_BUFFER = 13_000;
+const CLAUDE_USABLE_WINDOW_RESERVE = CLAUDE_MAX_OUTPUT_RESERVE + CLAUDE_AUTOCOMPACT_BUFFER;
+export function claudeEffectiveContextWindow(advertised) {
+    if (advertised == null)
+        return null;
+    if (advertised <= CLAUDE_USABLE_WINDOW_RESERVE)
+        return advertised;
+    return advertised - CLAUDE_USABLE_WINDOW_RESERVE;
+}
+// cc's `ey6` (was `hYB` pre-2.1.112) — context size of one assistant call. The
+// `output_tokens` slice matters: cc walks back to the latest assistant message
+// and adds its output to the input/cached/creation counters because that
+// generated content already exists in conversation history and would be
+// re-fed to the next call.
+function claudeContextUsedFromUsage(u) {
+    return (u.input ?? 0) + (u.cached ?? 0) + (u.cacheCreation ?? 0) + (u.output ?? 0);
+}
+function recomputeClaudeContextUsed(s) {
+    const total = claudeContextUsedFromUsage({
+        input: s.inputTokens,
+        cached: s.cachedInputTokens,
+        cacheCreation: s.cacheCreationInputTokens,
+        output: s.outputTokens,
+    });
+    s.contextUsedTokens = total > 0 ? total : null;
+}
+/**
+ * Tool names whose `tool_result` image content does NOT count as
+ * assistant-generated output and must NOT be re-rendered in the assistant
+ * card. These tools merely read existing files (user attachments, project
+ * assets) — the bytes already lived somewhere the user can see them, so
+ * surfacing them again in the assistant block creates a duplicate of the
+ * user's own upload below Claude's text reply.
+ *
+ * Genuine image producers (MCP image-gen tools, mermaid-mcp, chart, dalle-mcp,
+ * Codex built-in image_gen, …) are NOT in this set and continue to render
+ * normally.
+ */
+const CLAUDE_FILE_READING_TOOLS = new Set(['Read']);
+function isClaudeFileReadingTool(toolName) {
+    return !!toolName && CLAUDE_FILE_READING_TOOLS.has(toolName);
+}
+/**
+ * Walk a content array (assistant message body OR a tool_result.content array)
+ * and push any image entries into the stream state's `imageBlocks`, deduped by
+ * the first 64 chars of base64 data. Used during live parsing so the final
+ * StreamResult carries every image the turn produced.
+ */
+function accumulateClaudeImagesFromContent(content, s) {
+    if (!Array.isArray(content))
+        return;
+    for (const entry of content) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        if (entry.type === 'image') {
+            const block = claudeImageBlockFromEntry(entry);
+            if (!block)
+                continue;
+            const key = (entry.source?.data || '').slice(0, 64);
+            if (key && s.seenImageKeys?.has(key))
+                continue;
+            if (key)
+                s.seenImageKeys?.add(key);
+            s.imageBlocks?.push(block);
+        }
+        else if (entry.type === 'tool_result' && Array.isArray(entry.content)) {
+            // MCP / Skill tool_result with multimodal content — recurse for images,
+            // but skip tools that just read existing files (the bytes are already
+            // visible in the user's own upload bubble).
+            const toolName = entry.tool_use_id ? s.claudeToolsById?.get(entry.tool_use_id)?.name : null;
+            if (isClaudeFileReadingTool(toolName))
+                continue;
+            accumulateClaudeImagesFromContent(entry.content, s);
+        }
+    }
+}
+/**
+ * Read the server-assigned task id from a TaskCreate tool_result. Claude
+ * surfaces it via the structured `ev.toolUseResult.task.id` companion field,
+ * with a textual fallback ("Task #N created successfully: …") that we parse
+ * if the structured form is missing.
+ */
+function readClaudeTaskCreateId(ev, block) {
+    const structured = ev?.toolUseResult?.task?.id;
+    if (structured != null && String(structured).trim())
+        return String(structured).trim();
+    const content = block?.content;
+    if (typeof content === 'string') {
+        const match = content.match(/Task #(\d+)/);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+/**
+ * Rebuild s.plan from the accumulated TaskCreate / TaskUpdate state so the
+ * dashboard + IM plan card show the canonical Claude Code 2.x task progress.
+ * Order follows insertion order (matches the on-screen Claude task list).
+ */
+function rebuildClaudePlanFromTasks(s) {
+    if (!s.claudeTaskOrder?.length) {
+        // Nothing to render — leave s.plan alone so TodoWrite-era data (if any)
+        // doesn't get clobbered by an empty rebuild.
+        return;
+    }
+    const steps = [];
+    for (const id of s.claudeTaskOrder) {
+        const task = s.claudeTaskList.get(id);
+        if (!task)
+            continue;
+        const lowered = String(task.status || '').toLowerCase();
+        const status = lowered === 'completed' ? 'completed'
+            : lowered === 'in_progress' || lowered === 'inprogress' ? 'inProgress'
+                : 'pending';
+        steps.push({ step: task.subject, status });
+    }
+    s.plan = { explanation: null, steps };
+}
+function ensureClaudeBgAgentState(s) {
+    if (!s.bgAgentLaunchedToolUseIds)
+        s.bgAgentLaunchedToolUseIds = new Set();
+    if (!s.bgAgentCompletedToolUseIds)
+        s.bgAgentCompletedToolUseIds = new Set();
+    if (!s.bgBashToolUseIds)
+        s.bgBashToolUseIds = new Set();
+    if (!s.bgTaskIdToToolUse)
+        s.bgTaskIdToToolUse = new Map();
+    if (typeof s.lastTaskNotificationAt !== 'number')
+        s.lastTaskNotificationAt = 0;
+}
+/** Record a Task/Agent tool_use launched with `run_in_background: true`. */
+export function registerClaudeBackgroundAgentLaunch(s, toolUseId) {
+    const id = String(toolUseId || '').trim();
+    if (!id)
+        return;
+    ensureClaudeBgAgentState(s);
+    s.bgAgentLaunchedToolUseIds.add(id);
+}
+/**
+ * Record a `Bash` tool_use launched with `run_in_background: true`.
+ *
+ * Background Bash lives *inside the claude process* exactly like a
+ * backgrounded sub-agent: its tool_result is a launch ack, the real
+ * completion arrives later as a `<task-notification>` which re-invokes the
+ * model in the same process. Before this registration existed only Task/Agent
+ * launches counted as "pending background work" — a turn that backgrounded a
+ * Bash command would hit Stop, decideClaudeTuiStop saw pending=0 and
+ * terminated the PTY, killing the command and its future report-back turn
+ * (the「claude 后台任务一停止就被掐死」failure).
+ */
+export function registerClaudeBackgroundBashLaunch(s, toolUseId) {
+    const id = String(toolUseId || '').trim();
+    if (!id)
+        return;
+    ensureClaudeBgAgentState(s);
+    s.bgAgentLaunchedToolUseIds.add(id);
+    s.bgBashToolUseIds.add(id);
+}
+/** Launched background tasks (agents + bash) whose <task-notification> hasn't arrived yet. */
+export function pendingClaudeBackgroundAgentCount(s) {
+    const launched = s?.bgAgentLaunchedToolUseIds;
+    if (!launched?.size)
+        return 0;
+    const completed = s?.bgAgentCompletedToolUseIds;
+    let pending = 0;
+    for (const id of launched) {
+        if (!completed?.has(id))
+            pending++;
+    }
+    return pending;
+}
+/** Pending background *Bash* tasks specifically. Unlike agents (whose sidecar
+ *  JSONL keeps emitting events while alive), a background command is silent by
+ *  nature — callers use this to pick a longer hold/stall budget. */
+export function pendingClaudeBackgroundBashCount(s) {
+    const bash = s?.bgBashToolUseIds;
+    if (!bash?.size)
+        return 0;
+    const completed = s?.bgAgentCompletedToolUseIds;
+    let pending = 0;
+    for (const id of bash) {
+        if (!completed?.has(id))
+            pending++;
+    }
+    return pending;
+}
+/**
+ * Pull the background task id out of a launch ack. Claude Code's backgrounded
+ * Bash tool_result reads like "Command running in background with ID: bash_3
+ * (output: …)" — the id is what the later <task-notification> carries (its
+ * <tool-use-id> is often omitted for bash), so mapping id → tool_use here is
+ * what lets applyClaudeTaskNotification resolve the completion.
+ */
+export function extractClaudeBackgroundTaskId(content) {
+    let text = '';
+    if (typeof content === 'string')
+        text = content;
+    else if (Array.isArray(content)) {
+        text = content
+            .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+            .map((b) => b.text)
+            .join('\n');
+    }
+    else if (content && typeof content === 'object') {
+        try {
+            text = JSON.stringify(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!text || !/background/i.test(text))
+        return null;
+    const m = text.match(/\b(?:ID|id)\s*[:：]?\s*[`"']?([A-Za-z0-9][A-Za-z0-9_-]{1,63})/);
+    return m ? m[1] : null;
+}
+/**
+ * Pull the workflow runId (`wf_…`) out of a Workflow launch ack. The Workflow
+ * tool returns immediately with `{ runId }` and the orchestration runs in the
+ * background; its later `<task-notification>` may carry only that id (no
+ * `<tool-use-id>`), so mapping runId → tool_use here is what lets
+ * applyClaudeTaskNotification resolve the completion and release the PTY hold.
+ */
+export function extractClaudeWorkflowRunId(content) {
+    let text = '';
+    if (typeof content === 'string')
+        text = content;
+    else if (Array.isArray(content)) {
+        text = content
+            .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+            .map((b) => b.text)
+            .join('\n');
+    }
+    else if (content && typeof content === 'object') {
+        try {
+            text = JSON.stringify(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!text)
+        return null;
+    const m = text.match(/\bwf_[a-z0-9][a-z0-9-]{4,}\b/i);
+    return m ? m[0] : null;
+}
+/**
+ * Parse a `<task-notification>` wrapper out of a user event's content.
+ * Shape (observed, Claude Code 2.x):
+ *   <task-notification>
+ *     <task-id>a7a61bd5e0e76e0f3</task-id>
+ *     <tool-use-id>toolu_01MsPk…</tool-use-id>   ← omitted for orphaned tasks
+ *     <output-file>…</output-file>
+ *     <status>completed | failed | killed</status>
+ *     <summary>…</summary>
+ *   </task-notification>
+ */
+export function extractClaudeTaskNotification(content) {
+    let text = '';
+    if (typeof content === 'string')
+        text = content;
+    else if (Array.isArray(content)) {
+        text = content
+            .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+            .map((b) => b.text)
+            .join('\n');
+    }
+    if (!text || !text.includes('<task-notification>'))
+        return null;
+    const tag = (name) => {
+        const m = text.match(new RegExp(`<${name}>\\s*([^<]*?)\\s*</${name}>`));
+        return m ? (m[1].trim() || null) : null;
+    };
+    return { taskId: tag('task-id'), toolUseId: tag('tool-use-id'), status: tag('status') };
+}
+/**
+ * Fold a task-notification into the stream state: mark the matching background
+ * agent completed and flip its preview card status. Notifications for unknown
+ * tasks (orphans from a previous process, background Bash, …) still bump
+ * `lastTaskNotificationAt` — the TUI driver uses that timestamp to tell a
+ * pre-notification Stop hook apart from the model's post-resume Stop.
+ */
+export function applyClaudeTaskNotification(s, notification, eventAtMs) {
+    ensureClaudeBgAgentState(s);
+    // Prefer the event's own timestamp: when a JSONL flush delivers the
+    // notification and the wrap-up segment's Stop in one burst, parse-time would
+    // postdate the Stop and make a genuinely-fresh Stop look stale.
+    s.lastTaskNotificationAt = eventAtMs && Number.isFinite(eventAtMs) ? eventAtMs : Date.now();
+    const toolUseId = notification.toolUseId
+        || (notification.taskId ? s.bgTaskIdToToolUse.get(notification.taskId) : undefined)
+        || null;
+    if (!toolUseId)
+        return;
+    if (!s.bgAgentLaunchedToolUseIds.has(toolUseId) || s.bgAgentCompletedToolUseIds.has(toolUseId))
+        return;
+    s.bgAgentCompletedToolUseIds.add(toolUseId);
+    const sub = s.subAgents?.get(toolUseId);
+    if (sub && sub.status === 'running') {
+        const failed = /^(fail|kill|cancel|stop|abort|error)/i.test(notification.status || '');
+        sub.status = failed ? 'failed' : 'done';
+    }
+    const left = pendingClaudeBackgroundAgentCount(s);
+    pushRecentActivity(s.recentActivity, left > 0
+        ? `Background agent finished (${left} still running)`
+        : 'All background agents finished');
+    s.activity = s.recentActivity.join('\n');
+}
+export function claudeParse(ev, s) {
+    const t = ev.type || '';
+    // Sub-agent events (Task tool spawns a child agent) carry parent_tool_use_id
+    // pointing back to the parent's Task tool_use_id. They share the JSONL stream
+    // with parent events but must be isolated so their tool calls don't pollute
+    // the parent's activity list and their model/effort don't override the
+    // parent's runtime context.
+    const parentToolUseId = (typeof ev.parent_tool_use_id === 'string' && ev.parent_tool_use_id)
+        ? ev.parent_tool_use_id : null;
+    if (parentToolUseId) {
+        routeClaudeSubAgentEvent(ev, t, parentToolUseId, s);
+        return;
+    }
+    if (t === 'system') {
+        emitSessionIdUpdate(s, ev.session_id);
+        s.model = ev.model ?? s.model;
+        s.thinkingEffort = ev.thinking_level ?? s.thinkingEffort;
+        if (!s.byokContextWindow) {
+            const advertised = claudeContextWindowFromModel(s.model);
+            s.contextWindow = claudeEffectiveContextWindow(advertised) ?? s.contextWindow;
+        }
+    }
+    if (t === 'stream_event') {
+        const inner = ev.event || {};
+        if (inner.type === 'message_start') {
+            const u = inner.message?.usage;
+            // Per-call semantics: each LLM call inside a turn resets the counters,
+            // so the displayed In/Cached/Out and contextPercent describe the same
+            // call (matches cc's `LX(messages)` which returns the latest assistant
+            // usage, not a cumulative across calls).
+            // The finished call's output is folded into the turn-cumulative base
+            // first so `turnOutputTokens` keeps climbing across tool roundtrips.
+            s.turnOutputTokensBase = (s.turnOutputTokensBase ?? 0) + (s.outputTokens ?? 0);
+            s.inputTokens = u?.input_tokens ?? 0;
+            s.cachedInputTokens = u?.cache_read_input_tokens ?? 0;
+            s.cacheCreationInputTokens = u?.cache_creation_input_tokens ?? 0;
+            s.outputTokens = 0;
+            recomputeClaudeContextUsed(s);
+        }
+        // When a new text/thinking block starts after an earlier one (e.g. between
+        // a text block and a tool_use and back to text), insert a paragraph break
+        // so deltas from distinct blocks don't collapse into a single markdown
+        // paragraph.
+        if (inner.type === 'content_block_start') {
+            const blockType = inner.content_block?.type;
+            if (blockType === 'text' && s.text && !s.text.endsWith('\n\n')) {
+                s.text += s.text.endsWith('\n') ? '\n' : '\n\n';
+            }
+            else if (blockType === 'thinking' && s.thinking && !s.thinking.endsWith('\n\n')) {
+                s.thinking += s.thinking.endsWith('\n') ? '\n' : '\n\n';
+            }
+        }
+        if (inner.type === 'content_block_delta') {
+            const d = inner.delta || {};
+            if (d.type === 'thinking_delta')
+                s.thinking += d.thinking || '';
+            else if (d.type === 'text_delta')
+                s.text += d.text || '';
+        }
+        if (inner.type === 'message_delta') {
+            const d = inner.delta || {};
+            s.stopReason = d.stop_reason ?? s.stopReason;
+            const u = inner.usage;
+            if (u) {
+                // message_delta reports running totals for the active call. Per-call
+                // semantics: just overwrite — last value wins.
+                if (u.input_tokens != null)
+                    s.inputTokens = u.input_tokens;
+                if (u.cache_read_input_tokens != null)
+                    s.cachedInputTokens = u.cache_read_input_tokens;
+                if (u.cache_creation_input_tokens != null)
+                    s.cacheCreationInputTokens = u.cache_creation_input_tokens;
+                if (u.output_tokens != null)
+                    s.outputTokens = u.output_tokens;
+                recomputeClaudeContextUsed(s);
+            }
+        }
+        emitSessionIdUpdate(s, ev.session_id);
+        s.model = ev.model ?? s.model;
+        if (!s.byokContextWindow) {
+            const advertised = claudeContextWindowFromModel(s.model);
+            s.contextWindow = claudeEffectiveContextWindow(advertised) ?? s.contextWindow;
+        }
+    }
+    if (t === 'assistant') {
+        const msg = ev.message || {};
+        // Skip Claude CLI's synthetic feedback events on the live channel — they
+        // arrive as `assistant` events but represent runtime notices (no response,
+        // model error, …), not real Claude output. The historical jsonl reader
+        // converts them into `system_notice` blocks; on the live stream we just
+        // drop them so they don't pollute s.text / s.thinking.
+        if (msg.model === '<synthetic>') {
+            // …except the "selected model is unavailable" notice (404 model_not_found):
+            // a hard, non-retryable failure. The result event's text fallback below
+            // also catches it, but recording s.errors here upgrades the turn from a
+            // bare "(no textual response)" reply to a clear error + non-retryable
+            // stopReason (so doClaudeWithRetry won't loop on the same dead model).
+            if (!s.errors) {
+                const synthText = (msg.content || [])
+                    .filter((b) => b?.type === 'text').map((b) => b.text || '').join(' ');
+                if (ev.error === 'model_not_found' || detectClaudeModelError(synthText)) {
+                    s.stopReason = 'model_error';
+                    s.errors = [claudeModelErrorMessage(s.model)];
+                }
+            }
+            return;
+        }
+        const contents = msg.content || [];
+        const th = contents.filter((b) => b?.type === 'thinking').map((b) => b.thinking || '').join('\n\n');
+        const tx = contents.filter((b) => b?.type === 'text').map((b) => b.text || '').join('\n\n');
+        const toolUses = contents.filter((b) => b?.type === 'tool_use');
+        accumulateClaudeImagesFromContent(contents, s);
+        if (th && !s.thinking.trim())
+            s.thinking = th;
+        if (tx && !s.text.trim())
+            s.text = tx;
+        for (const block of toolUses) {
+            const toolId = String(block?.id || '').trim();
+            if (!toolId || s.seenClaudeToolIds.has(toolId))
+                continue;
+            const toolName = String(block?.name || 'Tool').trim() || 'Tool';
+            // TodoWrite → update plan instead of adding activity noise (Claude Code 1.x)
+            if (toolName === 'TodoWrite') {
+                const plan = parseTodoWriteAsPlan(block?.input);
+                if (plan)
+                    s.plan = plan;
+                s.seenClaudeToolIds.add(toolId);
+                s.claudeToolsById.set(toolId, { name: toolName, summary: 'Update plan' });
+                continue;
+            }
+            // TaskCreate / TaskUpdate → 2.x plan tools. Same intent as TodoWrite, but
+            // emitted one task at a time. Buffer TaskCreate inputs until the matching
+            // tool_result arrives with the server-assigned id; apply TaskUpdate status
+            // changes against the running map. Both rebuild s.plan so the dashboard /
+            // IM plan card keeps surfacing total + current progress.
+            if (toolName === 'TaskCreate') {
+                const subject = typeof block?.input?.subject === 'string' ? block.input.subject.trim() : '';
+                if (subject)
+                    s.pendingClaudeTaskCreates.set(toolId, { subject });
+                s.seenClaudeToolIds.add(toolId);
+                s.claudeToolsById.set(toolId, { name: toolName, summary: subject ? `Create task: ${subject}` : 'Create task' });
+                continue;
+            }
+            if (toolName === 'TaskUpdate') {
+                const taskId = String(block?.input?.taskId ?? '').trim();
+                const rawStatus = String(block?.input?.status ?? '').trim().toLowerCase();
+                if (taskId) {
+                    if (rawStatus === 'deleted') {
+                        s.claudeTaskList.delete(taskId);
+                        s.claudeTaskOrder = s.claudeTaskOrder.filter((id) => id !== taskId);
+                    }
+                    else if (rawStatus) {
+                        const existing = s.claudeTaskList.get(taskId);
+                        if (existing)
+                            existing.status = rawStatus;
+                    }
+                    rebuildClaudePlanFromTasks(s);
+                }
+                s.seenClaudeToolIds.add(toolId);
+                s.claudeToolsById.set(toolId, { name: toolName, summary: `Update task ${taskId || '?'} → ${rawStatus || 'unknown'}` });
+                continue;
+            }
+            // Task → represents a sub-agent invocation. Carve it out as its own
+            // streamed unit so the child's tool stream and model don't bleed into
+            // the parent's activity card.
+            if (toolName === 'Task' || toolName === 'Agent') {
+                const input = block?.input || {};
+                const subAgent = {
+                    id: toolId,
+                    kind: typeof input.subagent_type === 'string' ? input.subagent_type : null,
+                    description: typeof input.description === 'string' ? input.description : null,
+                    model: null,
+                    tools: [],
+                    status: 'running',
+                };
+                s.subAgents.set(toolId, subAgent);
+                if (input.run_in_background === true)
+                    registerClaudeBackgroundAgentLaunch(s, toolId);
+                s.seenClaudeToolIds.add(toolId);
+                s.claudeToolsById.set(toolId, { name: toolName, summary: subAgent.description || 'Run task' });
+                continue;
+            }
+            // Background Bash — same in-process lifecycle as a backgrounded agent:
+            // launch ack now, <task-notification> later. Register so the TUI driver
+            // holds the PTY open instead of SIGTERMing the command mid-flight.
+            if (toolName === 'Bash' && block?.input?.run_in_background === true) {
+                registerClaudeBackgroundBashLaunch(s, toolId);
+            }
+            // Workflow → multi-agent orchestration. ALWAYS backgrounded: the tool
+            // returns immediately with a runId and the orchestration keeps running
+            // *inside the claude process*, reporting completion via a later
+            // `<task-notification>` — the same in-process lifecycle as a
+            // run_in_background Task. Register it so decideClaudeTuiStop holds the PTY
+            // open instead of SIGTERMing the in-flight workflow when the launch
+            // segment's Stop fires (the「ultra 下 workflow 离线跑、TUI 误判结束退出把
+            // workflow 打断」failure — the workflow analogue of the bg-Bash fix above).
+            if (toolName === 'Workflow') {
+                registerClaudeBackgroundAgentLaunch(s, toolId);
+            }
+            const tool = {
+                name: toolName,
+                summary: summarizeClaudeToolUse(block?.name, block?.input || {}),
+                input: previewToolCallInput(toolName, block?.input),
+                status: 'running',
+            };
+            s.seenClaudeToolIds.add(toolId);
+            s.claudeToolsById.set(toolId, tool);
+            if (!s.claudeToolCallOrder)
+                s.claudeToolCallOrder = [];
+            s.claudeToolCallOrder.push(toolId);
+            pushRecentActivity(s.recentActivity, tool.summary);
+        }
+        s.activity = s.recentActivity.join('\n');
+        s.stopReason = msg.stop_reason ?? s.stopReason;
+    }
+    if (t === 'user') {
+        const msg = ev.message || {};
+        const contents = Array.isArray(msg.content) ? msg.content : [];
+        // Background-task completion notice. Claude Code injects these as user
+        // events when a `run_in_background` task finishes (or dies); they are the
+        // only completion signal backgrounded agents ever get — the Task tool's
+        // own tool_result fired back at launch time as an ack.
+        const notification = extractClaudeTaskNotification(msg.content);
+        if (notification) {
+            const eventAtMs = typeof ev.timestamp === 'string' ? Date.parse(ev.timestamp) : NaN;
+            applyClaudeTaskNotification(s, notification, Number.isFinite(eventAtMs) ? eventAtMs : null);
+        }
+        const toolResults = contents.filter((b) => b?.type === 'tool_result');
+        for (const block of toolResults) {
+            const toolId = String(block?.tool_use_id || '').trim();
+            // Dedup against tool_results already pushed by the TUI hook stream —
+            // PreToolUse / PostToolUse arrive in real time, JSONL eventually
+            // delivers the same events at end-of-turn and would otherwise re-push
+            // each summary into activity / re-process TaskCreate's plan entry.
+            if (toolId && s.seenClaudeToolResultIds?.has(toolId))
+                continue;
+            if (toolId) {
+                if (!s.seenClaudeToolResultIds)
+                    s.seenClaudeToolResultIds = new Set();
+                s.seenClaudeToolResultIds.add(toolId);
+            }
+            const tool = toolId ? s.claudeToolsById.get(toolId) : undefined;
+            // Skip TodoWrite / TaskCreate / TaskUpdate results from activity — plan
+            // card handles them. TaskCreate's tool_result carries the assigned task
+            // id, which we splice into the running task list before skipping.
+            if (tool?.name === 'TodoWrite')
+                continue;
+            if (tool?.name === 'TaskCreate') {
+                const pending = toolId ? s.pendingClaudeTaskCreates.get(toolId) : undefined;
+                const assignedId = readClaudeTaskCreateId(ev, block);
+                if (pending && assignedId) {
+                    s.pendingClaudeTaskCreates.delete(toolId);
+                    if (!s.claudeTaskList.has(assignedId))
+                        s.claudeTaskOrder.push(assignedId);
+                    s.claudeTaskList.set(assignedId, { subject: pending.subject, status: 'pending' });
+                    rebuildClaudePlanFromTasks(s);
+                }
+                continue;
+            }
+            if (tool?.name === 'TaskUpdate')
+                continue;
+            // Sub-agent tool_result closes out the sub-agent's lifecycle — flip its
+            // status and skip the regular activity append (the sub-agent card carries
+            // it). The result content text is the sub-agent's full response which
+            // would otherwise leak into the parent activity feed.
+            // Exception: a `run_in_background` launch returns its tool_result
+            // immediately as a mere ack — the agent is still running. Its real
+            // completion is the later <task-notification> (see the user branch).
+            if (tool?.name === 'Task' || tool?.name === 'Agent') {
+                const sub = s.subAgents.get(toolId);
+                if (sub) {
+                    const isBgLaunchAck = !block?.is_error
+                        && s.bgAgentLaunchedToolUseIds?.has(toolId)
+                        && !s.bgAgentCompletedToolUseIds?.has(toolId);
+                    if (!isBgLaunchAck)
+                        sub.status = block?.is_error ? 'failed' : 'done';
+                }
+                continue;
+            }
+            if (tool) {
+                tool.result = previewToolCallResult(block?.content);
+                tool.status = block?.is_error ? 'failed' : 'done';
+            }
+            // Background Bash launch ack → map its task id to the tool_use so the
+            // later <task-notification> (which usually omits <tool-use-id> for bash)
+            // can resolve and decrement the pending count.
+            if (tool?.name === 'Bash' && s.bgBashToolUseIds?.has(toolId)
+                && !s.bgAgentCompletedToolUseIds?.has(toolId)) {
+                const taskId = extractClaudeBackgroundTaskId(block?.content);
+                if (taskId && !s.bgTaskIdToToolUse.has(taskId))
+                    s.bgTaskIdToToolUse.set(taskId, toolId);
+            }
+            // Workflow launch ack carries the runId (wf_…). Map it → tool_use so a
+            // later <task-notification> that identifies the workflow only by task id
+            // (no <tool-use-id>) still resolves and decrements the pending count.
+            if (tool?.name === 'Workflow' && s.bgAgentLaunchedToolUseIds?.has(toolId)
+                && !s.bgAgentCompletedToolUseIds?.has(toolId)) {
+                const runId = extractClaudeWorkflowRunId(block?.content);
+                if (runId && !s.bgTaskIdToToolUse.has(runId))
+                    s.bgTaskIdToToolUse.set(runId, toolId);
+            }
+            pushRecentActivity(s.recentActivity, summarizeClaudeToolResult(tool, block, ev.tool_use_result));
+            // MCP / Skill tool_result with multimodal content — recurse for image
+            // entries so the final StreamResult carries them. Filesystem-reading
+            // tools (Read) are skipped: their image content is a copy of an
+            // existing file (often the user's own upload) and would otherwise be
+            // re-rendered below the assistant text.
+            if (Array.isArray(block.content) && !isClaudeFileReadingTool(tool?.name)) {
+                accumulateClaudeImagesFromContent(block.content, s);
+            }
+        }
+        s.activity = s.recentActivity.join('\n');
+    }
+    if (t === 'result') {
+        emitSessionIdUpdate(s, ev.session_id);
+        s.model = ev.model ?? s.model;
+        if (ev.is_error && ev.errors?.length)
+            s.errors = ev.errors;
+        if (ev.result && !s.text.trim())
+            s.text = ev.result;
+        // A model-unavailable turn carries a normal stop_reason on its result event
+        // (e.g. 'stop_sequence') that would otherwise clobber the 'model_error' the
+        // synthetic handler set — preserve it so the failure stays diagnosable.
+        if (s.stopReason !== 'model_error')
+            s.stopReason = ev.stop_reason ?? s.stopReason;
+        const u = ev.usage;
+        if (u) {
+            // Per-call semantics: the last message_start/message_delta snapshot is
+            // authoritative. Only fall back to result.usage when nothing arrived via
+            // stream_event (e.g. an early-exit error before any message_start).
+            const cached = u.cache_read_input_tokens ?? u.cached_input_tokens;
+            if (s.inputTokens == null && u.input_tokens != null)
+                s.inputTokens = u.input_tokens;
+            if (s.cachedInputTokens == null && cached != null)
+                s.cachedInputTokens = cached;
+            if (s.cacheCreationInputTokens == null && u.cache_creation_input_tokens != null) {
+                s.cacheCreationInputTokens = u.cache_creation_input_tokens;
+            }
+            if (s.outputTokens == null && u.output_tokens != null)
+                s.outputTokens = u.output_tokens;
+            recomputeClaudeContextUsed(s);
+        }
+        const mu = ev.modelUsage;
+        if (mu && typeof mu === 'object' && !s.byokContextWindow) {
+            for (const info of Object.values(mu)) {
+                // cc reports the *advertised* contextWindow on result.modelUsage; we
+                // store the *effective* (post-reservation) window so the percent
+                // matches cc's UM6 display formula.
+                if (info?.contextWindow > 0) {
+                    s.contextWindow = claudeEffectiveContextWindow(info.contextWindow) ?? info.contextWindow;
+                    break;
+                }
+            }
+        }
+    }
+}
+export function createClaudeStreamState(opts) {
+    // When BYOK is bound, the real context window (e.g. 1M for DeepSeek v4 Pro
+    // via OpenRouter) comes from the provider's cached /models listing — cc
+    // reports its own Claude-shaped fallback (200k) for unknown model ids, so
+    // we lock in the real value upfront and refuse to overwrite it from cc's
+    // event stream below.
+    const byokWindow = opts.byokContextWindow && opts.byokContextWindow > 0
+        ? opts.byokContextWindow
+        : null;
+    const byokProvider = opts.byokProviderName || null;
+    return {
+        sessionId: opts.sessionId,
+        text: '',
+        thinking: '',
+        msgs: [],
+        thinkParts: [],
+        model: opts.model,
+        thinkingEffort: opts.thinkingEffort,
+        errors: null,
+        inputTokens: null,
+        outputTokens: null,
+        cachedInputTokens: null,
+        cacheCreationInputTokens: null,
+        /** Output tokens from this turn's finished LLM calls — folded in when a
+         *  new call resets the per-call counter, so the turn total only climbs. */
+        turnOutputTokensBase: 0,
+        /** message.id of the LLM call whose usage `outputTokens` currently
+         *  reflects (TUI/JSONL mode, where there is no message_start marker). */
+        turnUsageMsgId: null,
+        contextWindow: byokWindow,
+        /** When set, ignore cc-advertised contextWindow updates from the stream. */
+        byokContextWindow: byokWindow,
+        /** BYOK provider display name surfaced in preview meta + IM footers. */
+        byokProviderName: byokProvider,
+        contextUsedTokens: null,
+        codexCumulative: null,
+        stopReason: null,
+        activity: '',
+        recentActivity: [],
+        plan: null,
+        // Claude Code 2.x replaced the single `TodoWrite` plan tool with two
+        // separate tools — `TaskCreate` (one task per call, server-assigned id)
+        // and `TaskUpdate` (taskId + status). We maintain an ordered map and
+        // rebuild s.plan whenever either fires so the dashboard / IM plan card
+        // keeps showing total / current progress just like the TodoWrite era.
+        claudeTaskList: new Map(),
+        claudeTaskOrder: [],
+        /** Pending TaskCreate tool_uses indexed by tool_use id — the input
+         *  carries the subject but Claude assigns the numeric task id only in
+         *  the matching tool_result, so we have to bridge the two halves. */
+        pendingClaudeTaskCreates: new Map(),
+        claudeToolsById: new Map(),
+        /** Insertion order of expandable tool-call rows (parent activity tools
+         *  only — plan tools and sub-agent launches have their own cards). Feeds
+         *  `StreamPreviewMeta.toolCalls` via buildStreamPreviewMeta. */
+        claudeToolCallOrder: [],
+        seenClaudeToolIds: new Set(),
+        subAgents: new Map(),
+        /** Tool_use ids of Task/Agent launches with `run_in_background: true`.
+         *  Their immediate tool_result is only a launch ack — real completion
+         *  arrives later as a `<task-notification>` user event. The TUI driver
+         *  reads the launched/completed delta to keep the PTY alive until every
+         *  background agent has actually finished (they live inside the claude
+         *  process; killing it would destroy them mid-flight). */
+        bgAgentLaunchedToolUseIds: new Set(),
+        /** Subset of bgAgentLaunchedToolUseIds whose <task-notification> arrived. */
+        bgAgentCompletedToolUseIds: new Set(),
+        /** Background task id (the `agent-<id>` sidecar stem / `<task-id>` tag) →
+         *  parent tool_use id. Fallback matcher for notifications that omit the
+         *  `<tool-use-id>` tag. */
+        bgTaskIdToToolUse: new Map(),
+        /** Wall-clock ms of the most recent <task-notification> parsed this turn. */
+        lastTaskNotificationAt: 0,
+        // Image blocks accumulated during the turn (user-attached on the request
+        // side, MCP / Skill tool_result on the response side). Surfaced in the
+        // final StreamResult so IM channels can dispatch images at end-of-turn.
+        imageBlocks: [],
+        /** Stable dedupe keys (sha-ish data prefixes) for image blocks already
+         *  added to `imageBlocks`. Lets repeated stream_event / assistant deltas
+         *  for the same image not pile up duplicates. */
+        seenImageKeys: new Set(),
+        // Wired to opts.onSessionId so claudeParse can broadcast id changes the
+        // instant cc surfaces them (see emitSessionIdUpdate in agent/utils.ts).
+        _emitSessionId: opts.onSessionId ?? null,
+    };
+}
+function resetClaudeTurnState(s, note) {
+    s.text = '';
+    s.thinking = '';
+    s.msgs = [];
+    s.thinkParts = [];
+    s.errors = null;
+    s.inputTokens = null;
+    s.outputTokens = null;
+    s.turnOutputTokensBase = 0;
+    s.turnUsageMsgId = null;
+    s.cachedInputTokens = null;
+    s.cacheCreationInputTokens = null;
+    s.contextUsedTokens = null;
+    s.stopReason = null;
+    s.activity = '';
+    s.recentActivity = [];
+    s.claudeToolsById = new Map();
+    s.claudeToolCallOrder = [];
+    s.subAgents = new Map();
+    s.seenClaudeToolIds = new Set();
+    s.bgAgentLaunchedToolUseIds = new Set();
+    s.bgAgentCompletedToolUseIds = new Set();
+    s.bgTaskIdToToolUse = new Map();
+    s.lastTaskNotificationAt = 0;
+    s.imageBlocks = [];
+    s.seenImageKeys = new Set();
+    if (note) {
+        pushRecentActivity(s.recentActivity, note);
+        s.activity = s.recentActivity.join('\n');
+    }
+}
+async function doClaudeInteractiveStream(opts) {
+    const start = Date.now();
+    const deadline = start + opts.timeout * 1000;
+    let stderr = '';
+    let lineCount = 0;
+    let timedOut = false;
+    let interrupted = false;
+    let stdinClosed = false;
+    let steerQueued = false;
+    let awaitingSteeredResponseStart = false;
+    let idleCloseTimer = null;
+    const s = createClaudeStreamState(opts);
+    const cmd = claudeCmd(opts);
+    const shellCmd = cmd.map(Q).join(' ');
+    agentLog(`[spawn] full command: cd ${Q(opts.workdir)} && ${shellCmd}`);
+    agentLog(`[spawn] timeout: ${opts.timeout}s session: ${opts.sessionId || '(new)'}`);
+    agentLog(`[spawn] prompt (stdin): "${opts.prompt.slice(0, 300)}${opts.prompt.length > 300 ? '…' : ''}"`);
+    const spawnEnv = { ...process.env, ...(opts.extraEnv || {}) };
+    scrubClaudeSessionContextEnv(spawnEnv);
+    const proc = spawn(shellCmd, {
+        cwd: opts.workdir,
+        env: spawnEnv,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: true,
+        detached: process.platform !== 'win32',
+    });
+    agentLog(`[spawn] pid=${proc.pid}`);
+    const closeInput = () => {
+        if (idleCloseTimer) {
+            clearTimeout(idleCloseTimer);
+            idleCloseTimer = null;
+        }
+        if (stdinClosed)
+            return;
+        stdinClosed = true;
+        try {
+            proc.stdin?.end();
+        }
+        catch { }
+    };
+    const emit = () => {
+        opts.onText(s.text, s.thinking, s.activity, buildStreamPreviewMeta(s), s.plan);
+    };
+    const abortStream = () => {
+        if (interrupted || proc.killed)
+            return;
+        interrupted = true;
+        s.stopReason = 'interrupted';
+        closeInput();
+        agentWarn(`[abort] user interrupt, closing stdin for graceful shutdown pid=${proc.pid}`);
+        // Wait until the session JSONL has stopped being written before SIGTERM.
+        // Claude CLI streams events on stdout (which we observe in real time) BEFORE
+        // flushing the matching JSONL line — and its signal handler is just
+        // `process.exit()`, which doesn't drain the async write queue. SIGTERMing
+        // on a fixed window races that flush: the dashboard's live snapshot would
+        // show N tool calls, then once it reloads from disk the persisted turn
+        // regresses below N (e.g. 30 → 27). Poll the JSONL size and SIGTERM only
+        // after it's been stable for FILE_STABLE_MS, or after MAX_WAIT_MS as a
+        // hard cap (a still-active LLM stream would never go stable on its own).
+        const sessionFile = s.sessionId
+            ? path.join(getHome(), '.claude', 'projects', claudeProjectDirName(opts.workdir), `${s.sessionId}.jsonl`)
+            : null;
+        const FILE_STABLE_MS = 600;
+        const POLL_MS = 100;
+        const MAX_WAIT_MS = 6000;
+        const startedAt = Date.now();
+        let lastSize = -1;
+        let lastChangedAt = startedAt;
+        const tick = () => {
+            if (proc.exitCode != null || proc.killed)
+                return;
+            let curSize = lastSize;
+            if (sessionFile) {
+                try {
+                    curSize = fs.statSync(sessionFile).size;
+                }
+                catch { /* file not yet created */ }
+            }
+            if (curSize !== lastSize) {
+                lastSize = curSize;
+                lastChangedAt = Date.now();
+            }
+            const stableFor = Date.now() - lastChangedAt;
+            const totalElapsed = Date.now() - startedAt;
+            // Without a JSONL path (very early abort, before sessionId is known) fall
+            // back to the legacy fixed grace window.
+            const shouldKill = !sessionFile
+                ? totalElapsed >= AGENT_GRACEFUL_ABORT_GRACE_MS
+                : (stableFor >= FILE_STABLE_MS || totalElapsed >= MAX_WAIT_MS);
+            if (shouldKill) {
+                const reason = !sessionFile
+                    ? `no JSONL, fixed grace ${totalElapsed}ms`
+                    : (stableFor >= FILE_STABLE_MS ? `JSONL stable ${stableFor}ms` : `max wait ${totalElapsed}ms`);
+                agentWarn(`[abort] ${reason}, killing process tree pid=${proc.pid}`);
+                terminateProcessTree(proc, { signal: 'SIGTERM', forceSignal: 'SIGKILL', forceAfterMs: 5000 });
+                return;
+            }
+            setTimeout(tick, POLL_MS);
+        };
+        setTimeout(tick, POLL_MS);
+    };
+    if (opts.abortSignal?.aborted)
+        abortStream();
+    opts.abortSignal?.addEventListener('abort', abortStream, { once: true });
+    const scheduleIdleClose = () => {
+        if (idleCloseTimer)
+            clearTimeout(idleCloseTimer);
+        idleCloseTimer = setTimeout(() => {
+            idleCloseTimer = null;
+            if (stdinClosed || interrupted || timedOut || proc.killed || proc.exitCode != null)
+                return;
+            agentLog(`[stdin] closing Claude input after ${CLAUDE_STEER_IDLE_CLOSE_MS}ms idle result window`);
+            closeInput();
+        }, CLAUDE_STEER_IDLE_CLOSE_MS);
+    };
+    const startsClaudeFollowup = (ev) => {
+        const evType = ev?.type || '';
+        if (evType === 'assistant')
+            return true;
+        if (evType !== 'stream_event')
+            return false;
+        const innerType = ev?.event?.type || '';
+        return innerType === 'message_start' || innerType === 'content_block_delta';
+    };
+    const sendInput = (prompt, attachments = [], note, kind = 'steer') => {
+        if (stdinClosed || interrupted || timedOut || proc.killed || proc.exitCode != null)
+            return false;
+        try {
+            proc.stdin?.write(buildClaudeUserMessage(prompt, attachments));
+            if (kind === 'steer') {
+                steerQueued = true;
+                if (idleCloseTimer) {
+                    clearTimeout(idleCloseTimer);
+                    idleCloseTimer = null;
+                }
+            }
+            if (note) {
+                pushRecentActivity(s.recentActivity, note);
+                s.activity = s.recentActivity.join('\n');
+                emit();
+            }
+            return true;
+        }
+        catch (error) {
+            agentWarn(`[stdin] failed to write Claude input: ${error?.message || error}`);
+            return false;
+        }
+    };
+    if (!sendInput(opts.prompt, opts.attachments || [], undefined, 'initial')) {
+        closeInput();
+    }
+    try {
+        opts.onSteerReady?.(async (prompt, attachments = []) => {
+            if (!sendInput(prompt, attachments, 'Queued steer input', 'steer'))
+                return false;
+            return true;
+        });
+    }
+    catch (error) {
+        agentWarn(`[stdin] onSteerReady error: ${error?.message || error}`);
+    }
+    proc.stderr?.on('data', (c) => {
+        const chunk = c.toString();
+        stderr += chunk;
+        agentLog(`[stderr] ${chunk.trim().slice(0, 200)}`);
+    });
+    const rl = createInterface({ input: proc.stdout, crlfDelay: Infinity });
+    rl.on('line', raw => {
+        if (Date.now() > deadline) {
+            timedOut = true;
+            s.stopReason = 'timeout';
+            closeInput();
+            agentWarn('[timeout] deadline exceeded, killing process tree');
+            terminateProcessTree(proc, { signal: 'SIGKILL' });
+            return;
+        }
+        const line = raw.trim();
+        if (!line || line[0] !== '{')
+            return;
+        lineCount++;
+        try {
+            const ev = JSON.parse(line);
+            const evType = ev.type || '?';
+            if (evType !== 'result' && idleCloseTimer) {
+                clearTimeout(idleCloseTimer);
+                idleCloseTimer = null;
+            }
+            if (awaitingSteeredResponseStart && startsClaudeFollowup(ev)) {
+                awaitingSteeredResponseStart = false;
+                steerQueued = false;
+                resetClaudeTurnState(s);
+            }
+            if (evType === 'system' || evType === 'result' || evType === 'assistant') {
+                agentLog(`[event] type=${evType} session=${ev.session_id || s.sessionId || '?'} model=${ev.model || s.model || '?'}`);
+            }
+            if (evType === 'stream_event') {
+                const inner = ev.event || {};
+                if (inner.type === 'message_start' || inner.type === 'message_delta') {
+                    agentLog(`[event] stream_event/${inner.type} session=${ev.session_id || s.sessionId || '?'}`);
+                }
+            }
+            claudeParse(ev, s);
+            if (evType === 'result') {
+                const hasError = !!ev.is_error || (Array.isArray(ev.errors) && ev.errors.length > 0);
+                if (hasError) {
+                    awaitingSteeredResponseStart = false;
+                    steerQueued = false;
+                    closeInput();
+                }
+                else if (steerQueued) {
+                    awaitingSteeredResponseStart = true;
+                    scheduleIdleClose();
+                }
+                else {
+                    closeInput();
+                }
+            }
+            emit();
+        }
+        catch { }
+    });
+    const hardTimer = setTimeout(() => {
+        timedOut = true;
+        s.stopReason = 'timeout';
+        closeInput();
+        agentWarn(`[timeout] hard deadline reached (${opts.timeout}s), killing process tree pid=${proc.pid}`);
+        terminateProcessTree(proc, { signal: 'SIGTERM', forceSignal: 'SIGKILL', forceAfterMs: 5000 });
+    }, opts.timeout * 1000 + AGENT_STREAM_HARD_KILL_GRACE_MS);
+    const [procOk, code] = await new Promise(resolve => {
+        proc.on('close', code => {
+            clearTimeout(hardTimer);
+            if (idleCloseTimer) {
+                clearTimeout(idleCloseTimer);
+                idleCloseTimer = null;
+            }
+            agentLog(`[exit] code=${code} lines_parsed=${lineCount}`);
+            resolve([code === 0, code]);
+        });
+        proc.on('error', e => {
+            clearTimeout(hardTimer);
+            if (idleCloseTimer) {
+                clearTimeout(idleCloseTimer);
+                idleCloseTimer = null;
+            }
+            agentError(`[error] ${e.message}`);
+            stderr += e.message;
+            resolve([false, -1]);
+        });
+    });
+    opts.abortSignal?.removeEventListener('abort', abortStream);
+    if (!s.text.trim() && s.msgs.length)
+        s.text = s.msgs.join('\n\n');
+    if (!s.thinking.trim() && s.thinkParts.length)
+        s.thinking = s.thinkParts.join('\n\n');
+    // Catch the Claude CLI's synthetic "API Error: …" assistant body (transient
+    // Anthropic 5xx / 529 Overloaded). Without this rewrite the raw error string
+    // gets surfaced into the IM card as if it were Claude's reply, and the
+    // retry wrapper in `doClaudeStream` can't tell a transient failure apart
+    // from a real short reply.
+    const apiErrorReason = detectClaudeApiError(s.text);
+    if (apiErrorReason) {
+        agentWarn(`[claude] upstream API error detected: ${apiErrorReason}`);
+        s.stopReason = 'api_error';
+        s.text = '';
+        if (!s.errors)
+            s.errors = [`Anthropic API error: ${apiErrorReason}`];
+    }
+    const errorText = joinErrorMessages(s.errors);
+    const ok = procOk && !s.errors && !timedOut && !interrupted;
+    const error = errorText
+        || (interrupted ? 'Interrupted by user.' : null)
+        || (timedOut ? `Timed out after ${opts.timeout}s before the agent reported completion.` : null)
+        || (!procOk ? (stderr.trim() || `Failed (exit=${code}).`) : null);
+    const incomplete = !ok || s.stopReason === 'max_tokens' || s.stopReason === 'timeout';
+    const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+    agentLog(`[result] ok=${ok && !s.errors} elapsed=${elapsed}s text=${s.text.length}chars thinking=${s.thinking.length}chars session=${s.sessionId || '?'}`);
+    if (errorText)
+        agentWarn(`[result] errors: ${errorText}`);
+    if (s.stopReason)
+        agentLog(`[result] stop_reason=${s.stopReason}`);
+    if (stderr.trim() && !procOk)
+        agentWarn(`[result] stderr: ${stderr.trim().slice(0, 300)}`);
+    return {
+        ok,
+        sessionId: s.sessionId,
+        workspacePath: null,
+        model: s.model,
+        thinkingEffort: s.thinkingEffort,
+        message: s.text.trim() || errorText || (procOk ? '(no textual response)' : `Failed (exit=${code}).\n\n${stderr.trim() || '(no output)'}`),
+        thinking: s.thinking.trim() || null,
+        elapsedS: (Date.now() - start) / 1000,
+        inputTokens: s.inputTokens,
+        outputTokens: s.outputTokens,
+        cachedInputTokens: s.cachedInputTokens,
+        cacheCreationInputTokens: s.cacheCreationInputTokens,
+        contextWindow: s.contextWindow,
+        contextUsedTokens: s.contextUsedTokens,
+        // Reuse the same calc as the live preview (computeContext) so the final
+        // footer % matches the running %. Previously this passed a fraction
+        // (used/window) into roundPercent, which expects a percent — divide-by-100
+        // bug that made the final read ~12% as ~0.1%.
+        contextPercent: computeContext(s).contextPercent,
+        codexCumulative: null,
+        error,
+        plan: s.plan,
+        stopReason: s.stopReason,
+        incomplete,
+        activity: s.activity.trim() || null,
+        assistantBlocks: s.imageBlocks.length ? [...s.imageBlocks] : undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Stream
+// ---------------------------------------------------------------------------
+export async function doClaudeStream(opts) {
+    const result = opts.onSteerReady
+        ? await doClaudeInteractiveStream(opts)
+        : await run(claudeCmd(opts), opts, claudeParse);
+    const retryText = `${result.error || ''}\n${result.message}`;
+    if (!result.ok && opts.sessionId && /no conversation found/i.test(retryText)) {
+        return doClaudeStream({ ...opts, sessionId: null });
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Sessions
+// ---------------------------------------------------------------------------
+export const claudeProjectDirName = encodePathAsDirName;
+/** Read native Claude Code sessions from ~/.claude/projects/{dirName}/*.jsonl */
+function extractClaudeTailQA(filePath) {
+    // Use a larger tail (1 MB) so we can reach past tool-result / assistant
+    // exchanges that follow the last real user question (which may be multi-MB
+    // due to embedded images).
+    const lines = readTailLines(filePath, 1024 * 1024);
+    let lastQuestion = null;
+    let lastAnswer = null;
+    let lastMessageText = null;
+    for (const raw of lines) {
+        if (!raw || raw[0] !== '{')
+            continue;
+        try {
+            const ev = JSON.parse(raw);
+            if (ev.type === 'user' && ev.isMeta !== true) {
+                const text = sanitizeSessionUserPreviewText(extractClaudeText(ev.message?.content, true));
+                if (text) {
+                    lastQuestion = shortValue(text, 500);
+                    lastMessageText = shortValue(text, 500);
+                }
+            }
+            else if (ev.type === 'assistant') {
+                const text = extractClaudeText(ev.message?.content).trim();
+                if (text) {
+                    lastAnswer = shortValue(text, 500);
+                    lastMessageText = shortValue(text, 500);
+                }
+            }
+        }
+        catch { /* skip */ }
+    }
+    return { lastQuestion, lastAnswer, lastMessageText };
+}
+// Per-file cache of the expensive content-derived fields. getNativeClaudeSessions
+// runs per dashboard session-list request AND per workspace×agent in the overview
+// fan-out; without this each call re-read + JSON-parsed every transcript in the
+// project dir. Keyed by (mtime,size) so any append/edit re-reads just that file.
+// `running`/`runState` are NOT cached — they depend on Date.now() - mtime, so they
+// are recomputed per call below.
+const nativeClaudeContentCache = new Map();
+function readNativeClaudeContent(filePath, stat) {
+    try {
+        // Read enough bytes to get past the system_prompt line (can be 20KB+) and
+        // reach the first user/assistant events for title and model extraction.
+        const fd = fs.openSync(filePath, 'r');
+        const buf = Buffer.alloc(65536);
+        const bytesRead = fs.readSync(fd, buf, 0, buf.length, 0);
+        fs.closeSync(fd);
+        const head = buf.toString('utf8', 0, bytesRead);
+        const lines = head.split('\n');
+        let title = null;
+        let model = null;
+        for (const line of lines) {
+            if (!line || line[0] !== '{')
+                continue;
+            try {
+                const ev = JSON.parse(line);
+                if (!title && ev.type === 'user' && ev.isMeta !== true) {
+                    const text = sanitizeSessionUserPreviewText(extractClaudeText(ev.message?.content, true));
+                    if (text) {
+                        const display = collapseSkillPrompt(text) ?? text;
+                        title = display.length <= 120 ? display : `${display.slice(0, 117).trimEnd()}...`;
+                    }
+                }
+                if (!model && ev.type === 'assistant' && ev.message?.model && ev.message.model !== '<synthetic>') {
+                    model = ev.message.model;
+                }
+                if (title && model)
+                    break;
+            }
+            catch { /* skip */ }
+        }
+        // Fallback: if the first user message line is too large (e.g. contains
+        // base64 images) JSON.parse above will fail.  Read a bigger chunk and
+        // regex-extract text blocks to find the actual user question.
+        if (!title) {
+            let scanStr = head;
+            if (stat.size > 65536) {
+                try {
+                    const fd2 = fs.openSync(filePath, 'r');
+                    const bigBuf = Buffer.alloc(Math.min(10 * 1024 * 1024, stat.size));
+                    const bigRead = fs.readSync(fd2, bigBuf, 0, bigBuf.length, 0);
+                    fs.closeSync(fd2);
+                    scanStr = bigBuf.toString('utf8', 0, bigRead);
+                }
+                catch { /* keep using head */ }
+            }
+            const re = /"type":"text","text":"((?:[^"\\]|\\.)*)"/g;
+            let m;
+            while ((m = re.exec(scanStr)) !== null) {
+                let raw = m[1]
+                    .replace(/\\n/g, ' ').replace(/\\t/g, ' ')
+                    .replace(/\\"/g, '"').replace(/\\\\/g, '\\')
+                    .replace(/\s+/g, ' ').trim();
+                if (!raw || raw.startsWith('<') || raw.startsWith('[Image:'))
+                    continue;
+                raw = stripInjectedPrompts(raw);
+                if (!raw)
+                    continue;
+                const display = collapseSkillPrompt(raw) ?? raw;
+                title = display.length <= 120 ? display : `${display.slice(0, 117).trimEnd()}...`;
+                break;
+            }
+        }
+        // Quick turn count: count real user messages (exclude tool_result and
+        // system-injected isMeta events — Skill outputs, resume prompts, etc.).
+        let numTurns = 0;
+        try {
+            const raw = fs.readFileSync(filePath, 'utf8');
+            const rawLines = raw.split('\n');
+            for (const rl of rawLines) {
+                if (rl.length <= 2 || !rl.includes('"type":"user"'))
+                    continue;
+                if (rl.includes('"tool_result"') || rl.includes('"isMeta":true'))
+                    continue;
+                numTurns++;
+            }
+        }
+        catch { /* ignore count errors */ }
+        const tailQA = extractClaudeTailQA(filePath);
+        return {
+            title,
+            model,
+            numTurns: numTurns || null,
+            createdAt: stat.birthtime.toISOString(),
+            lastQuestion: tailQA.lastQuestion,
+            lastAnswer: tailQA.lastAnswer,
+            lastMessageText: tailQA.lastMessageText,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function getNativeClaudeSessions(workdir, limit) {
+    const home = getHome();
+    if (!home)
+        return [];
+    const projectDir = path.join(home, '.claude', 'projects', claudeProjectDirName(workdir));
+    let entries;
+    try {
+        entries = fs.readdirSync(projectDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    // Stat first (cheap), sort newest-first, then read bodies only for as many as
+    // can surface: `limit` is applied to a recency-sorted merge downstream, so a
+    // transcript older than the top-`limit` can never appear in that view. Unchanged
+    // files come straight from the per-file content cache, so repeated list calls
+    // (dashboard polls, workspace×agent overview fan-out) don't re-parse the dir.
+    const files = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.jsonl'))
+            continue;
+        const filePath = path.join(projectDir, entry.name);
+        try {
+            files.push({ sessionId: entry.name.slice(0, -6), filePath, stat: fs.statSync(filePath) });
+        }
+        catch { /* skip */ }
+    }
+    files.sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs);
+    const selected = typeof limit === 'number' ? files.slice(0, Math.max(0, limit)) : files;
+    const sessions = [];
+    for (const { sessionId, filePath, stat } of selected) {
+        const cached = nativeClaudeContentCache.get(filePath);
+        let content;
+        if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+            content = cached.content;
+        }
+        else {
+            const parsed = readNativeClaudeContent(filePath, stat);
+            if (!parsed)
+                continue;
+            content = parsed;
+            nativeClaudeContentCache.set(filePath, { mtimeMs: stat.mtimeMs, size: stat.size, content });
+        }
+        const isRunning = isClaudeNativeSessionRunning(filePath, stat.mtimeMs);
+        sessions.push({
+            sessionId,
+            agent: 'claude',
+            workdir,
+            workspacePath: null,
+            model: content.model,
+            createdAt: content.createdAt,
+            title: content.title,
+            running: isRunning,
+            runState: isRunning ? 'running' : 'completed',
+            runDetail: null,
+            runUpdatedAt: stat.mtime.toISOString(),
+            classification: null,
+            userStatus: null,
+            userNote: null,
+            lastQuestion: content.lastQuestion,
+            lastAnswer: content.lastAnswer,
+            lastMessageText: content.lastMessageText,
+            migratedFrom: null,
+            migratedTo: null,
+            linkedSessions: [],
+            numTurns: content.numTurns,
+        });
+    }
+    return sessions;
+}
+function getClaudeSessions(workdir, limit) {
+    const resolvedWorkdir = path.resolve(workdir);
+    // Merge pikiloop-tracked sessions with native Claude sessions
+    const pikiloopSessions = listPikiloopSessions(resolvedWorkdir, 'claude').map(record => ({
+        sessionId: record.sessionId,
+        agent: 'claude',
+        workdir: record.workdir,
+        workspacePath: record.workspacePath,
+        threadId: record.threadId,
+        model: record.model,
+        createdAt: record.createdAt,
+        title: record.title,
+        running: record.runState === 'running',
+        runState: record.runState,
+        runDetail: record.runDetail,
+        runUpdatedAt: record.runUpdatedAt,
+        runPid: record.runPid,
+        classification: record.classification,
+        userStatus: record.userStatus,
+        userNote: record.userNote,
+        lastQuestion: record.lastQuestion,
+        lastAnswer: record.lastAnswer,
+        lastMessageText: record.lastMessageText,
+        migratedFrom: record.migratedFrom,
+        migratedTo: record.migratedTo,
+        linkedSessions: record.linkedSessions,
+        numTurns: record.numTurns ?? null,
+    }));
+    const nativeSessions = getNativeClaudeSessions(resolvedWorkdir, limit);
+    const merged = mergeManagedAndNativeSessions(pikiloopSessions, nativeSessions);
+    const sessions = typeof limit === 'number' ? merged.slice(0, limit) : merged;
+    const projectDir = path.join(getHome(), '.claude', 'projects', claudeProjectDirName(resolvedWorkdir));
+    agentLog(`[sessions:claude] workdir=${resolvedWorkdir} projectDir=${projectDir} projectDirExists=${fs.existsSync(projectDir)} ` +
+        `pikiloop=${pikiloopSessions.length} native=${nativeSessions.length} merged=${sessions.length}`);
+    return { ok: true, sessions, error: null };
+}
+// ---------------------------------------------------------------------------
+// Session tail
+// ---------------------------------------------------------------------------
+function extractClaudeText(content, skipSystemBlocks = false) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        if (block?.type === 'text' && typeof block.text === 'string') {
+            if (skipSystemBlocks && block.text.startsWith('<'))
+                continue;
+            parts.push(block.text);
+        }
+    }
+    // Join with blank line so consecutive text blocks render as separate markdown paragraphs.
+    return parts.join('\n\n');
+}
+function getClaudeSessionTail(opts) {
+    const limit = opts.limit ?? 4;
+    const projectDir = path.join(getHome(), '.claude', 'projects', claudeProjectDirName(opts.workdir));
+    const filePath = path.join(projectDir, `${opts.sessionId}.jsonl`);
+    if (!fs.existsSync(filePath)) {
+        return { ok: false, messages: [], error: 'Session file not found' };
+    }
+    try {
+        const lines = readTailLines(filePath);
+        const allMsgs = [];
+        for (const raw of lines) {
+            if (!raw || raw[0] !== '{')
+                continue;
+            try {
+                const ev = JSON.parse(raw);
+                if (ev.type === 'user') {
+                    const text = stripInjectedPrompts(extractClaudeText(ev.message?.content, true));
+                    if (text)
+                        allMsgs.push({ role: 'user', text });
+                }
+                else if (ev.type === 'assistant') {
+                    const text = extractClaudeText(ev.message?.content, true);
+                    if (text)
+                        allMsgs.push({ role: 'assistant', text });
+                }
+            }
+            catch { /* skip */ }
+        }
+        return { ok: true, messages: allMsgs.slice(-limit), error: null };
+    }
+    catch (e) {
+        return { ok: false, messages: [], error: e.message };
+    }
+}
+// ---------------------------------------------------------------------------
+// Session messages (full content)
+// ---------------------------------------------------------------------------
+/** Build an image MessageBlock from a Claude content entry of the shape
+ *  `{ type: 'image', source: { type: 'base64', media_type, data } }`. Returns
+ *  null when the source is missing or the encoded size exceeds the cap. */
+function claudeImageBlockFromEntry(entry) {
+    if (!entry || entry.type !== 'image' || !entry.source)
+        return null;
+    const source = entry.source;
+    if (source.type !== 'base64' || typeof source.data !== 'string')
+        return null;
+    // 12MB base64 ≈ 9MB binary — keep API payloads sane.
+    if (source.data.length > 12 * 1024 * 1024)
+        return null;
+    const mime = (source.media_type || 'image/png').toLowerCase();
+    return { type: 'image', content: `data:${mime};base64,${source.data}`, imageMime: mime };
+}
+/** Extract structured content blocks from Claude message content.
+ *  When `todoWriteToolIds` is provided, TodoWrite tool_use blocks are emitted
+ *  as `plan` blocks and their IDs are tracked so tool_results can be skipped.
+ *
+ *  When a `tool_result` block carries multimodal content (`content: [{type:'image',...}, ...]`),
+ *  the inner image entries are emitted as siblings of the textual tool_result —
+ *  this is the path MCP image-returning tools (mermaid-mcp, chart, dalle-mcp, …)
+ *  travel through. Filesystem-reading tools (Claude's `Read`) are excluded
+ *  via `toolNamesByUseId`: their image content is just an echo of an existing
+ *  file (often the user's own attachment) and re-rendering it under the
+ *  assistant card produces a confusing duplicate. */
+function extractClaudeBlocks(content, skipSystemBlocks = false, todoWriteToolIds, toolNamesByUseId) {
+    if (typeof content === 'string')
+        return [{ type: 'text', content }];
+    if (!Array.isArray(content))
+        return [];
+    const blocks = [];
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        if (block.type === 'text' && typeof block.text === 'string') {
+            if (skipSystemBlocks && block.text.startsWith('<'))
+                continue;
+            blocks.push({ type: 'text', content: block.text });
+        }
+        else if (block.type === 'thinking' && typeof block.thinking === 'string') {
+            blocks.push({ type: 'thinking', content: block.thinking });
+        }
+        else if (block.type === 'tool_use') {
+            // TodoWrite → emit as plan block instead of generic tool_use
+            if (block.name === 'TodoWrite' && todoWriteToolIds) {
+                const plan = parseTodoWriteAsPlan(block.input);
+                if (plan) {
+                    todoWriteToolIds.add(block.id);
+                    blocks.push({ type: 'plan', content: '', plan, toolId: block.id });
+                    continue;
+                }
+            }
+            const inputStr = block.input ? JSON.stringify(block.input, null, 2) : '';
+            blocks.push({ type: 'tool_use', content: inputStr, toolName: block.name || 'unknown', toolId: block.id });
+        }
+        else if (block.type === 'tool_result') {
+            const resultText = typeof block.content === 'string'
+                ? block.content
+                : Array.isArray(block.content)
+                    ? block.content.filter((c) => c?.type === 'text').map((c) => c.text).join('\n')
+                    : '';
+            blocks.push({ type: 'tool_result', content: resultText, toolId: block.tool_use_id });
+            // Recurse into multimodal tool_result content so MCP-returned images
+            // (and any future non-text inner types) surface alongside the textual
+            // tool_result rather than being silently dropped. Skip file-reading
+            // tools — their image content is an echo, not a new asset.
+            const toolName = block.tool_use_id ? toolNamesByUseId?.get(block.tool_use_id) : undefined;
+            if (Array.isArray(block.content) && !isClaudeFileReadingTool(toolName)) {
+                for (const inner of block.content) {
+                    const img = claudeImageBlockFromEntry(inner);
+                    if (img)
+                        blocks.push(img);
+                }
+            }
+        }
+        else if (block.type === 'image') {
+            const img = claudeImageBlockFromEntry(block);
+            if (img)
+                blocks.push(img);
+        }
+    }
+    return blocks;
+}
+/**
+ * Top-level XML wrapper tags that Claude Code injects into "user" events for
+ * non-user-authored content: background-task results, system reminders, IDE
+ * state, persisted output truncations, slash-command stdout, etc. The dashboard
+ * should never render these as a user bubble — they're conversation infra.
+ */
+const SYSTEM_INJECTED_USER_TAGS = new Set([
+    'task-notification',
+    'system-reminder',
+    'persisted-output',
+    'local-command-stdout',
+    'local-command-caveat',
+    'local-command-stderr',
+    'ide_opened_file',
+    'ide_diagnostics',
+    'ide_selection',
+    'event',
+    'analysis',
+    'case_id',
+    'tool-use-id',
+    'output-file',
+]);
+/**
+ * Detect Claude CLI's boilerplate `<synthetic>` responses that surface only
+ * because of TUI-resume bookkeeping — they carry no information for the user.
+ *
+ * The reproducible case: every `claude --resume <id>` in interactive mode
+ * writes a sentinel turn into the JSONL on startup, consisting of an
+ * `isMeta:true` user "Continue from where you left off." plus a `<synthetic>`
+ * "No response requested." acknowledgment. The print-mode driver doesn't hit
+ * this because `-p` skips the interactive resume nudge. Filtering it out here
+ * keeps the dashboard timeline clean across all driver paths.
+ */
+function isClaudeSyntheticResumeNoise(text) {
+    const t = (text || '').trim().toLowerCase();
+    if (!t)
+        return true;
+    return t === 'no response requested.' || t === 'no response requested';
+}
+/** Detect system-injected user events (compression summaries, interruption
+ *  markers, task-notifications, IDE state, etc.) that should not render as a
+ *  user message when parsing session JSONL. */
+function isSystemInjectedUserEvent(text) {
+    const trimmed = (text || '').trim();
+    if (!trimmed)
+        return true;
+    // Interruption markers injected by Claude Code
+    if (/^\[Request interrupted by user(?: for tool use)?\]$/i.test(trimmed))
+        return true;
+    // Leading XML wrapper from a known infra tag — these are never user-authored.
+    const leading = trimmed.match(/^<([a-z][a-z0-9_-]*)\b/i);
+    if (leading && SYSTEM_INJECTED_USER_TAGS.has(leading[1].toLowerCase()))
+        return true;
+    // Context compression summaries carry a recognizable opening marker. Detect
+    // by that marker, not length — long, legitimate user prompts (multi-paragraph
+    // briefs, pasted documents) routinely exceed any size threshold and must
+    // render as real user turns.
+    const lower = trimmed.toLowerCase();
+    const markers = ['continued from a previous', 'summary below covers', 'earlier portion of the conversation', 'here is a summary of', 'conversation summary'];
+    return markers.some(m => lower.includes(m));
+}
+function getClaudeSessionMessages(opts) {
+    const projectDir = path.join(getHome(), '.claude', 'projects', claudeProjectDirName(opts.workdir));
+    const filePath = path.join(projectDir, `${opts.sessionId}.jsonl`);
+    if (!fs.existsSync(filePath)) {
+        return { ok: false, messages: [], totalTurns: 0, error: 'Session file not found' };
+    }
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n').filter(l => l.trim());
+        // Parse raw events, merging consecutive same-role events into one message.
+        // Claude JSONL writes one event per content block (thinking, text, tool_use, tool_result).
+        // Consecutive assistant events form a single assistant message.
+        // User events with tool_result are system-injected and should be hidden;
+        // only user events with actual user text start a new user message.
+        const allMsgs = [];
+        const richMsgs = [];
+        let pendingRole = null;
+        let pendingTextParts = [];
+        let pendingBlocks = [];
+        /** Latest assistant-event usage snapshot — overwritten on each LLM call within a
+         *  turn so the flushed RichMessage carries the final call's context state, matching
+         *  the live `StreamPreviewMeta` semantics. */
+        let pendingUsage = null;
+        /** Per-call output tokens keyed by message.id — events of one call share an
+         *  id and carry running totals, so last-write-wins per id and the turn's
+         *  cumulative output is the sum across ids (→ `turnOutputTokens`). */
+        let pendingCallOutputs = new Map();
+        const todoWriteToolIds = new Set();
+        /**
+         * Sub-agent blocks live in `pendingBlocks` like any other block but we keep
+         * a side-table of references keyed by the Task tool_use_id so subsequent
+         * sub-agent assistant events (which carry parent_tool_use_id) can mutate
+         * the captured `subAgent` payload in place — that way the rendered turn
+         * shows the sub-agent's full tool stream without polluting the parent's
+         * tool list.
+         */
+        const subAgentBlocksById = new Map();
+        /** Tool ids belonging to sub-agents — their tool_results in user events are skipped from the parent activity. */
+        const subAgentToolIds = new Set();
+        /** Tool name keyed by tool_use_id — populated from assistant tool_use
+         *  events so the user-event tool_result loop can filter image content for
+         *  filesystem-reading tools (Read). */
+        const toolNamesByUseId = new Map();
+        const flush = () => {
+            if (!pendingRole)
+                return;
+            const text = pendingTextParts.join('\n\n');
+            if (text || pendingBlocks.length) {
+                allMsgs.push({ role: pendingRole, text });
+                let turnOutput = 0;
+                for (const v of pendingCallOutputs.values())
+                    turnOutput += v;
+                const usage = pendingRole === 'assistant' && pendingUsage
+                    ? buildClaudeTurnUsage(pendingUsage, turnOutput)
+                    : null;
+                richMsgs.push({ role: pendingRole, text, blocks: [...pendingBlocks], usage });
+            }
+            pendingRole = null;
+            pendingTextParts = [];
+            pendingBlocks = [];
+            pendingUsage = null;
+            pendingCallOutputs = new Map();
+            subAgentBlocksById.clear();
+            subAgentToolIds.clear();
+            toolNamesByUseId.clear();
+        };
+        for (const raw of lines) {
+            if (!raw || raw[0] !== '{')
+                continue;
+            try {
+                const ev = JSON.parse(raw);
+                const parentToolUseId = (typeof ev.parent_tool_use_id === 'string' && ev.parent_tool_use_id) ? ev.parent_tool_use_id : null;
+                if (parentToolUseId) {
+                    // Sub-agent emission — fold tool calls into the matching sub_agent block
+                    // and never let them surface as siblings of the parent's blocks.
+                    const block = subAgentBlocksById.get(parentToolUseId);
+                    if (!block?.subAgent)
+                        continue;
+                    const sub = block.subAgent;
+                    if (ev.type === 'assistant') {
+                        const model = ev.model ?? ev.message?.model;
+                        if (typeof model === 'string' && model.trim())
+                            sub.model = model;
+                        const contents = Array.isArray(ev.message?.content) ? ev.message.content : [];
+                        for (const inner of contents) {
+                            if (inner?.type !== 'tool_use')
+                                continue;
+                            const toolId = String(inner?.id || '').trim();
+                            if (!toolId)
+                                continue;
+                            const toolName = String(inner?.name || 'Tool').trim() || 'Tool';
+                            subAgentToolIds.add(toolId);
+                            const summary = toolName === 'TodoWrite' ? 'Update plan' : summarizeClaudeToolUse(inner?.name, inner?.input || {});
+                            if (!sub.tools.some(t => t.id === toolId)) {
+                                sub.tools.push({ id: toolId, name: toolName, summary });
+                            }
+                        }
+                    }
+                    continue;
+                }
+                if (ev.type === 'user') {
+                    // System-injected meta events (Skill tool results, /command stdout,
+                    // resume prompts) come through with `type:user` + `isMeta:true`. The
+                    // accompanying `message.content` is plain text (NOT a tool_result
+                    // block), so the regular `isToolResult` check below misses them and
+                    // they would otherwise render as a fake user bubble — splitting the
+                    // conversation into a phantom new turn (visible as a fresh
+                    // "Claude Code" divider mid-session). Re-attach the text to the
+                    // originating tool's activity feed when sourceToolUseID is known,
+                    // otherwise drop silently.
+                    if (ev.isMeta === true) {
+                        if (pendingRole === 'assistant') {
+                            const toolUseId = typeof ev.sourceToolUseID === 'string' ? ev.sourceToolUseID : '';
+                            if (toolUseId && !todoWriteToolIds.has(toolUseId) && !subAgentToolIds.has(toolUseId)) {
+                                const text = extractClaudeText(ev.message?.content, false);
+                                if (text) {
+                                    pendingBlocks.push({ type: 'tool_result', content: text, toolId: toolUseId });
+                                }
+                            }
+                        }
+                        continue;
+                    }
+                    const contentArr = ev.message?.content;
+                    const isToolResult = Array.isArray(contentArr)
+                        && contentArr.length > 0
+                        && contentArr.every((b) => b?.type === 'tool_result');
+                    if (isToolResult) {
+                        if (pendingRole === 'assistant') {
+                            for (const block of contentArr) {
+                                const toolUseId = block.tool_use_id;
+                                if (todoWriteToolIds.has(toolUseId))
+                                    continue;
+                                // Sub-agent inner tool results — already accounted for by the sub_agent block.
+                                if (subAgentToolIds.has(toolUseId))
+                                    continue;
+                                // Top-level tool_result for a sub-agent (Task / Agent) — close
+                                // out its lifecycle. The result content text is the sub-agent's
+                                // full final answer; surface it on the sub_agent block so the
+                                // dedicated card can render it instead of leaking into the
+                                // parent's tool_result feed.
+                                const subBlock = subAgentBlocksById.get(toolUseId);
+                                if (subBlock?.subAgent) {
+                                    subBlock.subAgent.status = block?.is_error ? 'failed' : 'done';
+                                    const resultText = typeof block.content === 'string'
+                                        ? block.content
+                                        : Array.isArray(block.content)
+                                            ? block.content.filter((c) => c?.type === 'text').map((c) => c.text).join('\n')
+                                            : '';
+                                    if (resultText)
+                                        subBlock.content = resultText;
+                                    continue;
+                                }
+                                const resultText = typeof block.content === 'string'
+                                    ? block.content
+                                    : Array.isArray(block.content)
+                                        ? block.content.filter((c) => c?.type === 'text').map((c) => c.text).join('\n')
+                                        : '';
+                                if (resultText) {
+                                    pendingBlocks.push({ type: 'tool_result', content: resultText, toolId: toolUseId });
+                                }
+                                // Multimodal tool_result content from MCP servers can include
+                                // image entries — surface them as siblings of the textual
+                                // tool_result so the rendered turn carries the image. Skip
+                                // filesystem-reading tools (Read): their image content is an
+                                // echo of an existing file (e.g. the user's own attachment)
+                                // and would otherwise be duplicated below the assistant text.
+                                const toolName = toolNamesByUseId.get(toolUseId);
+                                if (Array.isArray(block.content) && !isClaudeFileReadingTool(toolName)) {
+                                    for (const inner of block.content) {
+                                        const img = claudeImageBlockFromEntry(inner);
+                                        if (img)
+                                            pendingBlocks.push(img);
+                                    }
+                                }
+                            }
+                        }
+                        continue;
+                    }
+                    if (pendingRole === 'assistant') {
+                        const probe = extractClaudeText(ev.message?.content, true);
+                        if (isSystemInjectedUserEvent(probe))
+                            continue;
+                    }
+                    flush();
+                    const rawText = stripInjectedPrompts(extractClaudeText(ev.message?.content, true));
+                    const userBlocks = extractClaudeBlocks(ev.message?.content, true);
+                    const imageBlocks = userBlocks.filter(b => b.type === 'image');
+                    // TUI mode (claude-tui.ts) persists user `content` as a plain string
+                    // with leading `@/abs/path/image.png` mentions — that's how the TUI
+                    // ingests local images (it can't accept stream-json image blocks like
+                    // `-p` mode). The `extractClaudeBlocks` call above yields no image
+                    // blocks for that shape; lift the mentions into structured image
+                    // blocks via the shared pipeline so the dashboard renders thumbnails
+                    // instead of raw paths. Also resolves the "first message drops the
+                    // image" + "queued message drops the image" symptoms because the
+                    // optimisticBridgesImages bridge (SessionPanel) was previously
+                    // falling open: the server-side user text contained the @-path while
+                    // the optimistic pendingPrompt did not, so the bridge's text-equality
+                    // check failed and the no-image server bubble replaced the
+                    // optimistic one.
+                    let displayText = rawText;
+                    if (typeof ev.message?.content === 'string' && imageBlocks.length === 0) {
+                        const recoveredPaths = new Set();
+                        for (const absPath of extractClaudeAtMentionImagePaths(rawText)) {
+                            const block = attachAgentImage({ imagePath: absPath });
+                            if (!block)
+                                continue;
+                            imageBlocks.push(block);
+                            recoveredPaths.add(absPath);
+                        }
+                        // Only strip the mentions we successfully turned into image blocks;
+                        // leave unresolved ones (file deleted/moved) in the text so the
+                        // user sees what was attached even when we can't render it.
+                        if (recoveredPaths.size) {
+                            displayText = rawText.replace(CLAUDE_AT_MENTION_IMAGE_RE, (full, leading, p) => recoveredPaths.has(p) ? (leading || '') : full);
+                        }
+                    }
+                    const text = displayText.replace(SESSION_PREVIEW_IMAGE_PLACEHOLDER_RE, '').replace(/\s+/g, ' ').trim();
+                    if (text || imageBlocks.length) {
+                        pendingRole = 'user';
+                        pendingTextParts = text ? [text] : [];
+                        pendingBlocks = text ? [{ type: 'text', content: text }, ...imageBlocks] : [...imageBlocks];
+                    }
+                }
+                else if (ev.type === 'assistant') {
+                    // `model:"<synthetic>"` is Claude CLI's out-of-band channel — emitted
+                    // when the runtime needs to tell the user something *as if* the
+                    // assistant spoke ("No response requested.", "There's an issue with
+                    // the selected model…", etc.). Surface it as a `system_notice` block
+                    // rather than a real text reply: the content stays visible (so model
+                    // errors and other meaningful feedback aren't lost), but it renders
+                    // as a notice tile instead of impersonating a Claude turn.
+                    if (ev.message?.model === '<synthetic>') {
+                        const noticeText = extractClaudeText(ev.message?.content, true).trim();
+                        // Suppress TUI-resume startup noise. When `claude --resume <id>`
+                        // boots in interactive mode it injects a sentinel turn — an
+                        // `isMeta:true` user "Continue from where you left off." followed
+                        // by a `<synthetic>` "No response requested." acknowledgment.
+                        // This is harmless internal book-keeping; rendering it as a
+                        // yellow notice on every TUI-mode turn just pollutes the UI.
+                        if (isClaudeSyntheticResumeNoise(noticeText))
+                            continue;
+                        if (pendingRole === 'user')
+                            flush();
+                        pendingRole = 'assistant';
+                        if (noticeText)
+                            pendingBlocks.push({ type: 'system_notice', content: noticeText });
+                        continue;
+                    }
+                    if (pendingRole === 'user')
+                        flush();
+                    pendingRole = 'assistant';
+                    const u = ev.message?.usage;
+                    if (u && typeof u === 'object') {
+                        const numOrNull = (v) => typeof v === 'number' && Number.isFinite(v) ? v : null;
+                        const prevModel = pendingUsage ? pendingUsage.model : null;
+                        pendingUsage = {
+                            input: numOrNull(u.input_tokens),
+                            output: numOrNull(u.output_tokens),
+                            cacheRead: numOrNull(u.cache_read_input_tokens),
+                            cacheCreation: numOrNull(u.cache_creation_input_tokens),
+                            model: typeof ev.message?.model === 'string' ? ev.message.model : prevModel,
+                        };
+                        // Per-call output for the turn-cumulative counter. Same-id events
+                        // carry running totals → keep the last value per call.
+                        const output = numOrNull(u.output_tokens);
+                        if (output != null) {
+                            const msgId = typeof ev.message?.id === 'string' && ev.message.id ? ev.message.id : '(no-id)';
+                            pendingCallOutputs.set(msgId, output);
+                        }
+                    }
+                    const text = extractClaudeText(ev.message?.content, true);
+                    if (text)
+                        pendingTextParts.push(text);
+                    // Record tool names from this assistant turn before extracting blocks
+                    // so any tool_result that follows in a later user event can be
+                    // attributed to the right tool (Read → skip image recursion, etc.).
+                    const assistantContents = Array.isArray(ev.message?.content) ? ev.message.content : [];
+                    for (const inner of assistantContents) {
+                        if (inner?.type === 'tool_use' && typeof inner.id === 'string' && typeof inner.name === 'string') {
+                            toolNamesByUseId.set(inner.id, inner.name);
+                        }
+                    }
+                    const blocks = extractClaudeBlocks(ev.message?.content, true, todoWriteToolIds, toolNamesByUseId);
+                    // Convert sub-agent tool_use blocks into sub_agent placeholders we
+                    // can later mutate. Claude Code surfaces the Task tool as `Agent` in
+                    // its v2 stream format; accept both names so older sessions still
+                    // parse correctly.
+                    const contents = Array.isArray(ev.message?.content) ? ev.message.content : [];
+                    for (let i = 0; i < blocks.length; i++) {
+                        const block = blocks[i];
+                        if (block.type !== 'tool_use')
+                            continue;
+                        if (block.toolName !== 'Task' && block.toolName !== 'Agent')
+                            continue;
+                        const raw = contents.find((c) => c?.type === 'tool_use' && c?.id === block.toolId);
+                        const input = raw?.input || {};
+                        const subAgent = {
+                            id: block.toolId || '',
+                            kind: typeof input.subagent_type === 'string' ? input.subagent_type : null,
+                            description: typeof input.description === 'string' ? input.description : null,
+                            model: null,
+                            tools: [],
+                            status: 'running',
+                        };
+                        const subBlock = { type: 'sub_agent', content: '', toolId: block.toolId, subAgent };
+                        blocks[i] = subBlock;
+                        if (subAgent.id)
+                            subAgentBlocksById.set(subAgent.id, subBlock);
+                    }
+                    pendingBlocks.push(...blocks);
+                }
+            }
+            catch { /* skip malformed lines */ }
+        }
+        flush();
+        // Hydrate sub_agent blocks from sidecar files. Claude Code stores each
+        // sub-agent's full transcript in
+        //   ~/.claude/projects/<dir>/<session-id>/subagents/agent-<id>.jsonl
+        // alongside an `agent-<id>.meta.json` carrying the agentType. The parent
+        // session only records the Agent tool_use + tool_result; without this step
+        // the sub-agent card has no tool list.
+        const subAgentsDir = path.join(projectDir, opts.sessionId, 'subagents');
+        if (fs.existsSync(subAgentsDir))
+            hydrateSubAgentBlocksFromSidecar(richMsgs, subAgentsDir);
+        return applyTurnWindow(allMsgs, opts, opts.rich ? richMsgs : undefined);
+    }
+    catch (e) {
+        return { ok: false, messages: [], totalTurns: 0, error: e.message };
+    }
+}
+/**
+ * Walk a session's `subagents/` directory and merge each sidecar's tool stream
+ * onto the matching `sub_agent` block (matched by description, the only stable
+ * shared field between parent and child sessions). Best-effort — silent on any
+ * I/O or parse failure.
+ */
+function hydrateSubAgentBlocksFromSidecar(richMsgs, subAgentsDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(subAgentsDir);
+    }
+    catch {
+        return;
+    }
+    const sidecars = new Map();
+    for (const name of entries) {
+        if (!name.endsWith('.jsonl'))
+            continue;
+        const id = name.replace(/\.jsonl$/, '');
+        const metaPath = path.join(subAgentsDir, `${id}.meta.json`);
+        let metaKind = null;
+        let metaDescription = null;
+        try {
+            const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+            metaKind = typeof meta?.agentType === 'string' ? meta.agentType : null;
+            metaDescription = typeof meta?.description === 'string' ? meta.description : null;
+        }
+        catch { /* meta optional */ }
+        const tools = [];
+        let model = null;
+        try {
+            const content = fs.readFileSync(path.join(subAgentsDir, name), 'utf-8');
+            for (const raw of content.split('\n')) {
+                if (!raw || raw[0] !== '{')
+                    continue;
+                let ev;
+                try {
+                    ev = JSON.parse(raw);
+                }
+                catch {
+                    continue;
+                }
+                if (ev.type !== 'assistant')
+                    continue;
+                const msg = ev.message || {};
+                if (typeof msg.model === 'string' && msg.model.trim())
+                    model = msg.model;
+                const contents = Array.isArray(msg.content) ? msg.content : [];
+                for (const block of contents) {
+                    if (block?.type !== 'tool_use')
+                        continue;
+                    const toolId = String(block?.id || '').trim();
+                    if (!toolId || tools.some(t => t.id === toolId))
+                        continue;
+                    const toolName = String(block?.name || 'Tool').trim() || 'Tool';
+                    const summary = toolName === 'TodoWrite' ? 'Update plan' : summarizeClaudeToolUse(block?.name, block?.input || {});
+                    tools.push({ id: toolId, name: toolName, summary });
+                }
+            }
+        }
+        catch {
+            continue;
+        }
+        if (metaDescription) {
+            sidecars.set(metaDescription, { kind: metaKind, tools, model });
+        }
+    }
+    if (sidecars.size === 0)
+        return;
+    for (const msg of richMsgs) {
+        for (const block of msg.blocks) {
+            if (block.type !== 'sub_agent' || !block.subAgent || !block.subAgent.description)
+                continue;
+            const sidecar = sidecars.get(block.subAgent.description);
+            if (!sidecar)
+                continue;
+            if (!block.subAgent.kind && sidecar.kind)
+                block.subAgent.kind = sidecar.kind;
+            if (!block.subAgent.model && sidecar.model)
+                block.subAgent.model = sidecar.model;
+            if (block.subAgent.tools.length === 0 && sidecar.tools.length > 0)
+                block.subAgent.tools = sidecar.tools;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Models
+// ---------------------------------------------------------------------------
+const CLAUDE_MODELS = [
+    { id: 'claude-fable-5', alias: 'fable' },
+    { id: 'claude-opus-4-8', alias: 'opus' },
+    { id: 'claude-sonnet-4-6', alias: 'sonnet' },
+    { id: 'claude-haiku-4-5-20251001', alias: 'haiku' },
+];
+// ---------------------------------------------------------------------------
+// Usage
+// ---------------------------------------------------------------------------
+// The account-usage query below hits api.anthropic.com/api/oauth/usage, which is
+// itself rate-limited. The dashboard rebuilds agent status ~every 30s (plus a
+// forced refresh on usage-ring hover), and querying that often trips the
+// endpoint's 429 — which (since we treat a query error as "unknown") blanks the
+// header usage ring entirely. Quota windows (5h/7d) move slowly, so we query at
+// most once per this interval and serve the last good result in between
+// (including across transient 429s), decoupling usage cadence from how often
+// agent status is rebuilt.
+const CLAUDE_USAGE_QUERY_TTL_MS = 5 * 60_000;
+const claudeUsageCache = { lastGood: null, lastAttemptAt: 0 };
+function getClaudeOAuthToken() {
+    // `security` is macOS-only; other platforms store Claude creds differently
+    // (DPAPI on Windows, libsecret on Linux) and Claude Code manages those itself.
+    if (!IS_MAC)
+        return null;
+    try {
+        const raw = execSync('security find-generic-password -s "Claude Code-credentials" -w 2>/dev/null', {
+            encoding: 'utf-8', timeout: 3000,
+        }).trim();
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        return parsed?.claudeAiOauth?.accessToken || null;
+    }
+    catch {
+        return null;
+    }
+}
+function getClaudeUsageFromOAuth() {
+    const token = getClaudeOAuthToken();
+    if (!token)
+        return null;
+    try {
+        const raw = execSync(`curl -s --max-time 5 -H "Authorization: Bearer ${token}" -H "anthropic-beta: oauth-2025-04-20" -H "Content-Type: application/json" "https://api.anthropic.com/api/oauth/usage"`, { encoding: 'utf-8', timeout: 8000 }).trim();
+        if (!raw || raw[0] !== '{')
+            return null;
+        const data = JSON.parse(raw);
+        const capturedAt = new Date().toISOString();
+        const apiError = data?.error;
+        if (apiError && typeof apiError === 'object') {
+            // The usage query endpoint itself returned an error (e.g. 429 rate
+            // limit on the query API).  This does NOT reflect the user's actual
+            // Claude usage status, so fall through to telemetry instead of
+            // reporting a misleading "limit_reached".
+            return null;
+        }
+        const makeWindow = (label, entry) => {
+            if (!entry || typeof entry !== 'object')
+                return null;
+            const usedPercent = roundPercent(entry.utilization);
+            if (usedPercent == null)
+                return null;
+            const remainingPercent = Math.max(0, Math.round((100 - usedPercent) * 10) / 10);
+            const resetAt = typeof entry.resets_at === 'string' ? entry.resets_at : null;
+            let resetAfterSeconds = null;
+            if (resetAt) {
+                const resetAtMs = Date.parse(resetAt);
+                if (Number.isFinite(resetAtMs))
+                    resetAfterSeconds = Math.max(0, Math.round((resetAtMs - Date.now()) / 1000));
+            }
+            return {
+                label, usedPercent, remainingPercent, resetAt, resetAfterSeconds,
+                status: usedPercent >= 100 ? 'limit_reached' : usedPercent >= 80 ? 'warning' : 'allowed',
+            };
+        };
+        const windows = [];
+        for (const [label, key] of [['5h', 'five_hour'], ['7d', 'seven_day'], ['7d Opus', 'seven_day_opus'], ['7d Sonnet', 'seven_day_sonnet'], ['Extra', 'extra_usage']]) {
+            const w = makeWindow(label, data[key]);
+            if (w)
+                windows.push(w);
+        }
+        if (!windows.length)
+            return null;
+        const overallStatus = windows.some(w => w.status === 'limit_reached') ? 'limit_reached'
+            : windows.some(w => w.status === 'warning') ? 'warning' : 'allowed';
+        return { ok: true, agent: 'claude', source: 'oauth-api', capturedAt, status: overallStatus, windows, error: null };
+    }
+    catch {
+        return null;
+    }
+}
+function getClaudeUsageFromTelemetry(home, model) {
+    const telemetryRoot = path.join(home, '.claude', 'telemetry');
+    if (!fs.existsSync(telemetryRoot))
+        return null;
+    const preferredFamily = modelFamily(model);
+    let bestAny = null;
+    let bestMatch = null;
+    try {
+        const files = fs.readdirSync(telemetryRoot)
+            .filter(name => name.endsWith('.json'))
+            .map(name => ({ full: path.join(telemetryRoot, name), mtime: fs.statSync(path.join(telemetryRoot, name)).mtimeMs }))
+            .sort((a, b) => b.mtime - a.mtime)
+            .slice(0, 50);
+        for (const file of files) {
+            const lines = fs.readFileSync(file.full, 'utf-8').trim().split('\n');
+            for (let i = lines.length - 1; i >= 0; i--) {
+                const raw = lines[i];
+                if (!raw || raw[0] !== '{' || !raw.includes('tengu_claudeai_limits_status_changed'))
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    continue;
+                }
+                const data = parsed?.event_data;
+                if (data?.event_name !== 'tengu_claudeai_limits_status_changed')
+                    continue;
+                const capturedAtMs = Date.parse(data.client_timestamp || '');
+                if (!Number.isFinite(capturedAtMs))
+                    continue;
+                let meta = data.additional_metadata;
+                if (typeof meta === 'string') {
+                    try {
+                        meta = JSON.parse(meta);
+                    }
+                    catch {
+                        meta = null;
+                    }
+                }
+                const hoursTillReset = Number(meta?.hoursTillReset);
+                const candidate = {
+                    capturedAtMs, capturedAt: new Date(capturedAtMs).toISOString(),
+                    status: typeof meta?.status === 'string' ? meta.status : null,
+                    hoursTillReset: Number.isFinite(hoursTillReset) ? hoursTillReset : null,
+                    model: typeof data.model === 'string' ? data.model : null,
+                };
+                if (!bestAny || candidate.capturedAtMs > bestAny.capturedAtMs)
+                    bestAny = candidate;
+                if (preferredFamily && candidate.model?.toLowerCase().includes(preferredFamily)) {
+                    if (!bestMatch || candidate.capturedAtMs > bestMatch.capturedAtMs)
+                        bestMatch = candidate;
+                }
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    const chosen = bestMatch || bestAny;
+    if (!chosen)
+        return null;
+    const status = normalizeUsageStatus(chosen.status);
+    const resetAfterSeconds = chosen.hoursTillReset == null ? null : Math.max(0, Math.round(chosen.hoursTillReset * 3600));
+    const resetAt = resetAfterSeconds == null ? null : new Date(chosen.capturedAtMs + resetAfterSeconds * 1000).toISOString();
+    // Build a locale-neutral label from capture age (e.g. "3h ago", "2d ago")
+    const ageMs = Date.now() - chosen.capturedAtMs;
+    const ageMins = Math.round(ageMs / 60_000);
+    const ageLabel = ageMins < 1 ? '<1m ago' : ageMins < 60 ? `${ageMins}m ago` : ageMins < 1440 ? `${Math.round(ageMins / 60)}h ago` : `${Math.round(ageMins / 1440)}d ago`;
+    const windows = [{ label: ageLabel, usedPercent: null, remainingPercent: null, resetAt, resetAfterSeconds, status }];
+    return { ok: true, agent: 'claude', source: 'telemetry', capturedAt: chosen.capturedAt, status, windows, error: null };
+}
+function claudeSessionTranscriptPath(workdir, sessionId) {
+    const home = getHome();
+    if (!home || !workdir || !sessionId)
+        return '';
+    return path.join(home, '.claude', 'projects', encodePathAsDirName(workdir), `${sessionId}.jsonl`);
+}
+/**
+ * Scan a claude session transcript for the latest native /goal state. Returns
+ * null when no `goal_status` attachment is present.
+ */
+export function getClaudeNativeGoal(workdir, sessionId) {
+    const file = claudeSessionTranscriptPath(workdir, sessionId);
+    if (!file || !fs.existsSync(file))
+        return null;
+    // Goal status lines are tiny attachments. Walk the tail (1 MB) to find the
+    // last one — tail covers all realistic session sizes without parsing every
+    // line of a long transcript.
+    const lines = readTailLines(file, 1024 * 1024);
+    let latest = null;
+    for (const raw of lines) {
+        if (!raw || raw[0] !== '{')
+            continue;
+        // Cheap pre-filter so we only JSON.parse the relevant subset.
+        if (!raw.includes('"goal_status"'))
+            continue;
+        try {
+            const ev = JSON.parse(raw);
+            const att = ev?.attachment;
+            if (!att || att.type !== 'goal_status')
+                continue;
+            const condition = typeof att.condition === 'string' ? att.condition : '';
+            const met = !!att.met;
+            const ts = typeof ev.timestamp === 'string' ? Date.parse(ev.timestamp) : NaN;
+            latest = {
+                condition,
+                met,
+                status: met || !condition ? 'complete' : 'active',
+                updatedAtMs: Number.isFinite(ts) ? ts : Date.now(),
+            };
+        }
+        catch { /* skip */ }
+    }
+    // After auto-clear (met:true) claude still leaves the goal_status line in the
+    // transcript; pikiloop treats "no active goal" as null so the bridge mirrors
+    // the codex semantics where `goal_get` returns null after a clear.
+    if (latest && latest.met)
+        return null;
+    return latest;
+}
+/** Build the user-prompt that triggers claude's native `/goal <condition>` slash command. */
+export function buildClaudeSetGoalPrompt(objective) {
+    return `/goal ${objective.trim()}`;
+}
+/** Build the user-prompt that triggers claude's native `/goal clear` slash command. */
+export function buildClaudeClearGoalPrompt() {
+    return '/goal clear';
+}
+// ---------------------------------------------------------------------------
+// Driver
+// ---------------------------------------------------------------------------
+/**
+ * Claude turns default to the real interactive TUI under PTY — usage stays
+ * inside the Pro/Max subscription quota. `claude -p` calls (headless / print
+ * mode) bill against the separate Agent SDK credit pool that Anthropic split
+ * out on 2026-06-15, so we keep that off the hot path.
+ *
+ * Opt out to the legacy print path with `PIKILOOP_CLAUDE_PRINT=1` (also
+ * accepts `=true` / `=yes` / `=on`). For backwards compat the older
+ * `PIKILOOP_CLAUDE_TUI=0` / `=false` / `=no` / `=off` is honoured too.
+ *
+ * When TUI startup fails (node-pty missing, prebuilt helper unusable, PTY
+ * allocation refused in a sandbox, …) the dispatcher automatically falls
+ * through to the print-mode driver so pikiloop still works — at the cost of
+ * the calls landing on the Agent SDK credit pool. The fallback is logged so
+ * users can investigate.
+ */
+export function isClaudePrintModeForced() {
+    const print = (process.env.PIKILOOP_CLAUDE_PRINT ?? '').trim().toLowerCase();
+    if (print === '1' || print === 'true' || print === 'yes' || print === 'on')
+        return true;
+    // Legacy env var: PIKILOOP_CLAUDE_TUI=0 (or false/no/off) explicitly opts
+    // back to print mode. Truthy values are now the default behaviour and a
+    // no-op.
+    const tui = (process.env.PIKILOOP_CLAUDE_TUI ?? '').trim().toLowerCase();
+    if (tui === '0' || tui === 'false' || tui === 'no' || tui === 'off')
+        return true;
+    return false;
+}
+/**
+ * Single-attempt dispatch: print mode when the resolved access mode is 'api'
+ * (or, when no explicit mode was threaded, when forced via env), otherwise TUI
+ * mode with print-mode fallback if TUI prerequisites are missing (node-pty
+ * absent, PTY allocation refused, …).
+ *
+ * `opts.claudeAccessMode` is authoritative when set — the bot resolves it from
+ * the per-agent config so a live dashboard toggle takes effect on the next
+ * spawned turn. Env (isClaudePrintModeForced) is only the fallback for callers
+ * that don't thread a mode (the `pikiloop run` one-shot path).
+ */
+async function doClaudeStreamOnce(opts) {
+    const printMode = opts.claudeAccessMode
+        ? opts.claudeAccessMode === 'api'
+        : isClaudePrintModeForced();
+    if (printMode) {
+        agentLog(`[claude] print mode (-p) — ${opts.claudeAccessMode === 'api' ? 'access mode: api (Agent SDK credits)' : 'forced via env'}`);
+        return doClaudeStream(opts);
+    }
+    try {
+        const mod = await import('./claude-tui.js');
+        return await mod.doClaudeTuiStream(opts);
+    }
+    catch (err) {
+        // TUI prerequisite failed (node-pty missing, PTY allocation refused, etc.).
+        // Fall back to print mode so pikiloop stays functional — with the caveat
+        // that this turn lands on the Agent SDK credit pool.
+        agentWarn(`[claude] TUI unavailable (${err?.message || err}); falling back to -p — this turn bills the Agent SDK credit pool`);
+        return doClaudeStream(opts);
+    }
+}
+/**
+ * Backoff schedule (in ms) for retrying transient Anthropic upstream failures
+ * — 529 Overloaded, 5xx, gateway timeouts. Total wait budget ~30s before we
+ * surface the failure to the user. Non-retryable errors (auth, quota,
+ * context-length) skip the loop and fail fast.
+ */
+const CLAUDE_API_RETRY_BACKOFFS_MS = [4000, 12000];
+function makeOverloadFriendlyResult(result, reason, attempts) {
+    const wait = CLAUDE_API_RETRY_BACKOFFS_MS.slice(0, attempts).reduce((sum, ms) => sum + ms, 0);
+    const elapsedNote = wait > 0 ? ` (retried ${attempts}× over ${Math.round(wait / 1000)}s)` : '';
+    const message = [
+        `Anthropic API temporarily overloaded${elapsedNote}.`,
+        `Reason from upstream: ${reason}.`,
+        'Please re-send your last message in a moment — your session is intact and will resume from where it stopped.',
+    ].join(' ');
+    return {
+        ...result,
+        ok: false,
+        incomplete: true,
+        stopReason: 'api_error',
+        message,
+        error: `Anthropic API error: ${reason}`,
+    };
+}
+/**
+ * Driver-entry wrapper. Detects the Claude CLI's synthetic "API Error: …"
+ * assistant turn and re-issues the request with backoff for retryable upstream
+ * conditions (Overloaded, 5xx, timeouts). Non-retryable failures surface
+ * immediately. After the budget is exhausted, the final result carries a
+ * friendly human-readable explanation in `message` so the IM card doesn't
+ * dump raw "API Error: Overloaded" text on the user.
+ */
+/**
+ * Continuation prompt for stall recovery. The frozen process already accepted
+ * and partially executed the user's prompt (it sits in the transcript), so the
+ * resumed process must NOT receive the original prompt again — it gets an
+ * explicit "pick up where you left off" instead.
+ */
+const CLAUDE_STALL_RESUME_PROMPT = '[pikiloop] The previous agent process stalled mid-turn and was restarted. '
+    + 'Continue the task from where it left off — do not start over or repeat work that already completed.';
+/** At most one automatic resume per turn; a second stall surfaces to the user. */
+const CLAUDE_STALL_RESUME_LIMIT = 1;
+async function doClaudeWithRetry(opts) {
+    let lastResult = await doClaudeStreamOnce(opts);
+    // Mid-turn stall recovery. The TUI driver SIGTERMs a frozen claude process
+    // (stopReason 'stalled' — see decideClaudeTuiStall in claude-tui.ts) instead
+    // of letting the IM card spin forever. Resume the same session once with a
+    // continuation prompt so the turn picks up where the frozen process died.
+    let stallResumes = 0;
+    while (lastResult.stopReason === 'stalled'
+        && stallResumes < CLAUDE_STALL_RESUME_LIMIT
+        && !opts.abortSignal?.aborted) {
+        const stalledSessionId = lastResult.sessionId || opts.sessionId;
+        if (!stalledSessionId)
+            break;
+        stallResumes++;
+        agentWarn(`[claude] turn stalled mid-flight; auto-resuming session ${stalledSessionId.slice(0, 8)} (${stallResumes}/${CLAUDE_STALL_RESUME_LIMIT})`);
+        lastResult = await doClaudeStreamOnce({
+            ...opts,
+            sessionId: stalledSessionId,
+            forkOf: undefined,
+            prompt: CLAUDE_STALL_RESUME_PROMPT,
+            attachments: undefined,
+        });
+    }
+    if (lastResult.stopReason === 'stalled') {
+        // Still stalled after the resume budget (or no session id to resume).
+        // Surface a self-explanatory failure instead of the raw error text.
+        return {
+            ...lastResult,
+            ok: false,
+            incomplete: true,
+            message: [
+                'The agent process stalled mid-turn and could not be auto-recovered (a known claude CLI mid-turn freeze).',
+                'Your session is intact — re-send your message (or say "continue") to pick up where it stopped.',
+            ].join(' '),
+        };
+    }
+    let attempts = 0;
+    // Use the error text recorded by detectClaudeApiError-driven branches to
+    // decide retry: lastResult.error is "Anthropic API error: <reason>" on
+    // detection, undefined otherwise.
+    const reasonOf = (r) => {
+        if (r.stopReason !== 'api_error')
+            return null;
+        const m = (r.error || '').match(/^Anthropic API error:\s*(.+)$/i);
+        return m ? m[1].trim() : null;
+    };
+    while (attempts < CLAUDE_API_RETRY_BACKOFFS_MS.length) {
+        const reason = reasonOf(lastResult);
+        if (!reason || !isRetryableClaudeApiError(reason))
+            break;
+        const wait = CLAUDE_API_RETRY_BACKOFFS_MS[attempts];
+        attempts++;
+        agentWarn(`[claude] API error "${reason}", retry ${attempts}/${CLAUDE_API_RETRY_BACKOFFS_MS.length} after ${wait}ms`);
+        if (opts.abortSignal?.aborted) {
+            agentWarn('[claude] retry skipped — abort signal already fired');
+            break;
+        }
+        await new Promise(r => setTimeout(r, wait));
+        if (opts.abortSignal?.aborted) {
+            agentWarn('[claude] retry skipped after backoff — abort signal fired');
+            break;
+        }
+        // Resume the same session so we don't restart from scratch. The previous
+        // attempt may have written a synthetic "API Error" assistant block into
+        // the JSONL; Claude resumes past it and re-answers the user's prompt.
+        const nextOpts = {
+            ...opts,
+            sessionId: lastResult.sessionId || opts.sessionId,
+        };
+        lastResult = await doClaudeStreamOnce(nextOpts);
+    }
+    const finalReason = reasonOf(lastResult);
+    if (finalReason) {
+        return makeOverloadFriendlyResult(lastResult, finalReason, attempts);
+    }
+    return lastResult;
+}
+class ClaudeDriver {
+    id = 'claude';
+    cmd = 'claude';
+    thinkLabel = 'Thinking';
+    capabilities = { fork: true, modelSwitch: true, workflow: true };
+    // Claude Code BYOK routes through ANTHROPIC_BASE_URL — accepts both
+    // first-party Anthropic and any openai-compatible provider that exposes an
+    // Anthropic-protocol-shaped endpoint (OpenRouter `/api/v1`, DeepSeek
+    // `/anthropic/v1`, …). cf. src/model/injector.ts:claudeInjector.
+    acceptedProviderKinds = ['anthropic', 'openai-compatible'];
+    async doStream(opts) {
+        return doClaudeWithRetry(opts);
+    }
+    async getSessions(workdir, limit) {
+        return getClaudeSessions(workdir, limit);
+    }
+    async getSessionTail(opts) {
+        return getClaudeSessionTail(opts);
+    }
+    async getSessionMessages(opts) {
+        return getClaudeSessionMessages(opts);
+    }
+    async listModels(_opts) {
+        return { agent: 'claude', models: [...CLAUDE_MODELS], sources: [], note: null };
+    }
+    getUsage(opts) {
+        const home = getHome();
+        if (!home)
+            return emptyUsage('claude', 'HOME is not set.');
+        const telemetry = () => getClaudeUsageFromTelemetry(home, opts.model)
+            || emptyUsage('claude', 'No recent Claude usage data found.');
+        // Throttle the rate-limited OAuth usage query (see CLAUDE_USAGE_QUERY_TTL_MS).
+        // Within the window we reuse the last good result rather than re-querying on
+        // every agent-status rebuild, so a transient query-API 429 can't blank the
+        // ring between successful polls.
+        const now = Date.now();
+        if (now - claudeUsageCache.lastAttemptAt < CLAUDE_USAGE_QUERY_TTL_MS) {
+            return claudeUsageCache.lastGood ?? telemetry();
+        }
+        claudeUsageCache.lastAttemptAt = now;
+        const oauth = getClaudeUsageFromOAuth();
+        if (oauth) {
+            claudeUsageCache.lastGood = oauth;
+            return oauth;
+        }
+        // OAuth unavailable (non-mac, no token, or transient 429): keep showing the
+        // last good windows if we have any; otherwise fall back to telemetry.
+        return claudeUsageCache.lastGood ?? telemetry();
+    }
+    async deleteNativeSession(workdir, sessionId) {
+        const file = claudeSessionTranscriptPath(workdir, sessionId);
+        if (!file || !fs.existsSync(file))
+            return [];
+        try {
+            fs.rmSync(file, { force: true });
+            return [file];
+        }
+        catch {
+            return [];
+        }
+    }
+    shutdown() { }
+}
+registerDriver(new ClaudeDriver());