specrails-core 6.4.0 → 6.5.0

package/dist/agent-runtime/session/domain/usage.d.ts

@@ -0,0 +1,54 @@
+import { type Usage, type UsageSemantics } from './types.js';
+/** Raw values as a provider reported them for one turn (or one sub-agent thread). */
+export interface ReportedUsage {
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+    cacheReadTokens?: number | null;
+    cacheWriteTokens?: number | null;
+    totalTokens?: number | null;
+    costUsd?: number | null;
+    model?: string | null;
+}
+/**
+ * Last known cumulative provider totals for one provider session (or thread).
+ * `null` means unknown — e.g. a session resumed from history we never observed —
+ * which is different from a fresh session whose baseline is 0.
+ */
+export interface UsageBaseline {
+    costUsd: number | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cacheReadTokens: number | null;
+    cacheWriteTokens: number | null;
+}
+export declare const FRESH_BASELINE: UsageBaseline;
+export declare const UNKNOWN_BASELINE: UsageBaseline;
+export interface TurnUsageResult {
+    usage: Usage;
+    baseline: UsageBaseline;
+    /** Values that went backwards (provider reset); the reported value was used as the delta. */
+    resets: string[];
+}
+/**
+ * Convert what the provider reported into this turn's usage, according to the
+ * driver's declared semantics. Verified against real CLIs:
+ * - Claude reports USD cumulative per session, including across `--resume`,
+ *   and tokens per turn.
+ * - Codex reports tokens cumulative per thread and no USD.
+ * Missing values stay null; nothing is ever coerced to zero.
+ */
+export declare function computeTurnUsage(semantics: UsageSemantics, baseline: UsageBaseline, reported: ReportedUsage): TurnUsageResult;
+/** USD per million tokens; supplied by the host, never guessed by Core. */
+export interface RateCard {
+    inputPerMTok: number;
+    outputPerMTok: number;
+    cacheReadPerMTok?: number;
+    cacheWritePerMTok?: number;
+}
+/**
+ * Fill a missing cost from a rate card and flag it as an estimate. A billed cost
+ * is never overwritten; usage with no billable tokens stays null.
+ */
+export declare function withEstimatedCost(usage: Usage, rate: RateCard | null): Usage;
+/** Sum usages for display breakdowns; a sum is null only when every part is null. */
+export declare function sumUsage(items: readonly Usage[]): Usage;

package/dist/agent-runtime/session/domain/usage.js

@@ -0,0 +1,86 @@
+import { EMPTY_USAGE } from './types.js';
+const COUNTERS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens'];
+export const FRESH_BASELINE = Object.freeze({ costUsd: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 });
+export const UNKNOWN_BASELINE = Object.freeze({ costUsd: null, inputTokens: null, outputTokens: null, cacheReadTokens: null, cacheWriteTokens: null });
+function finite(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+}
+/** Delta of a cumulative counter against its baseline. Unknown baseline → unknown delta. */
+function delta(reported, base, key, resets) {
+    if (reported === null)
+        return { value: null, next: base };
+    if (base === null)
+        return { value: null, next: reported };
+    if (reported < base) {
+        resets.push(key);
+        return { value: reported, next: reported };
+    }
+    return { value: reported - base, next: reported };
+}
+/**
+ * Convert what the provider reported into this turn's usage, according to the
+ * driver's declared semantics. Verified against real CLIs:
+ * - Claude reports USD cumulative per session, including across `--resume`,
+ *   and tokens per turn.
+ * - Codex reports tokens cumulative per thread and no USD.
+ * Missing values stay null; nothing is ever coerced to zero.
+ */
+export function computeTurnUsage(semantics, baseline, reported) {
+    const resets = [];
+    const next = { ...baseline };
+    const usage = { ...EMPTY_USAGE, model: reported.model ?? null };
+    // A reported total is only meaningful per turn; cumulative totals are not tracked as a baseline.
+    if (semantics.tokens === 'per-turn')
+        usage.totalTokens = finite(reported.totalTokens);
+    if (semantics.costUsd === 'session-cumulative') {
+        const result = delta(finite(reported.costUsd), baseline.costUsd, 'costUsd', resets);
+        usage.costUsd = result.value;
+        next.costUsd = result.next;
+    }
+    else if (semantics.costUsd === 'per-turn') {
+        usage.costUsd = finite(reported.costUsd);
+    }
+    for (const key of COUNTERS) {
+        if (semantics.tokens === 'per-turn') {
+            usage[key] = finite(reported[key]);
+        }
+        else if (semantics.tokens === 'cumulative') {
+            const result = delta(finite(reported[key]), baseline[key], key, resets);
+            usage[key] = result.value;
+            next[key] = result.next;
+        }
+    }
+    return { usage, baseline: next, resets };
+}
+/**
+ * Fill a missing cost from a rate card and flag it as an estimate. A billed cost
+ * is never overwritten; usage with no billable tokens stays null.
+ */
+export function withEstimatedCost(usage, rate) {
+    if (usage.costUsd !== null || !rate)
+        return usage;
+    const parts = [
+        [usage.inputTokens, rate.inputPerMTok],
+        [usage.outputTokens, rate.outputPerMTok],
+        [usage.cacheReadTokens, rate.cacheReadPerMTok],
+        [usage.cacheWriteTokens, rate.cacheWritePerMTok],
+    ];
+    if (!parts.some(([tokens]) => (tokens ?? 0) > 0))
+        return usage;
+    const cost = parts.reduce((sum, [tokens, price]) => sum + ((tokens ?? 0) * (price ?? 0)) / 1_000_000, 0);
+    return { ...usage, costUsd: cost, costEstimated: true };
+}
+/** Sum usages for display breakdowns; a sum is null only when every part is null. */
+export function sumUsage(items) {
+    const total = { ...EMPTY_USAGE };
+    for (const item of items) {
+        for (const key of [...COUNTERS, 'totalTokens', 'costUsd']) {
+            const value = item[key];
+            if (value !== null)
+                total[key] = (total[key] ?? 0) + value;
+        }
+        total.costEstimated = total.costEstimated || item.costEstimated;
+        total.model = total.model ?? item.model;
+    }
+    return total;
+}

package/dist/agent-runtime/session/drivers/claude/argv.d.ts

@@ -0,0 +1,19 @@
+import type { DriverOpenSpec } from '../../ports.js';
+/** Tools that launch sub-agents in Claude Code; removed when policy disables sub-agents. */
+export declare const CLAUDE_SUBAGENT_TOOLS: readonly ["Agent", "Task"];
+export declare const CLAUDE_READ_ONLY_TOOLS: readonly ["Read", "Grep", "Glob"];
+/**
+ * Map an open spec + policy to Claude Code argv. Lists are passed as one
+ * comma-separated argument (variadic flags would otherwise swallow later args).
+ * `systemPromptFile` is used instead of an inline prompt when provided
+ * (long prompts / Windows command-line limits).
+ */
+export declare function claudeArgs(spec: DriverOpenSpec, options?: {
+    systemPromptFile?: string;
+}): string[];
+/**
+ * Environment for the Claude process. Native sub-agents run on another model
+ * through `CLAUDE_CODE_SUBAGENT_MODEL` (verified live: a haiku parent ran a
+ * sonnet sub-agent). Claude has no per-sub-agent effort.
+ */
+export declare function claudeEnv(policy: DriverOpenSpec['policy'], base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/agent-runtime/session/drivers/claude/argv.js

@@ -0,0 +1,67 @@
+import { nativeSubagentsAllowed } from '../../domain/policy.js';
+/** Tools that launch sub-agents in Claude Code; removed when policy disables sub-agents. */
+export const CLAUDE_SUBAGENT_TOOLS = ['Agent', 'Task'];
+export const CLAUDE_READ_ONLY_TOOLS = ['Read', 'Grep', 'Glob'];
+function mcpConfig(servers) {
+    return JSON.stringify({
+        mcpServers: Object.fromEntries(servers.map((server) => [server.name, server.url
+                ? { type: 'http', url: server.url, ...(server.headers ? { headers: server.headers } : {}) }
+                : { command: server.command, args: server.args ?? [], ...(server.env ? { env: server.env } : {}) }])),
+    });
+}
+/**
+ * Map an open spec + policy to Claude Code argv. Lists are passed as one
+ * comma-separated argument (variadic flags would otherwise swallow later args).
+ * `systemPromptFile` is used instead of an inline prompt when provided
+ * (long prompts / Windows command-line limits).
+ */
+export function claudeArgs(spec, options = {}) {
+    const policy = spec.policy;
+    const args = [
+        '-p',
+        '--input-format', 'stream-json',
+        '--output-format', 'stream-json',
+        '--verbose',
+        '--replay-user-messages',
+        '--setting-sources', 'project,local',
+        '--model', spec.model,
+    ];
+    if (spec.effort)
+        args.push('--effort', spec.effort);
+    if (options.systemPromptFile)
+        args.push('--system-prompt-file', options.systemPromptFile);
+    else if (spec.systemPrompt)
+        args.push('--system-prompt', spec.systemPrompt);
+    if (policy.permissions === 'bypass')
+        args.push('--dangerously-skip-permissions');
+    else
+        args.push('--permission-mode', policy.permissions === 'read-only' ? 'plan' : 'acceptEdits');
+    if (policy.tools.mode === 'none')
+        args.push('--tools', '');
+    else if (policy.tools.mode === 'read-only')
+        args.push('--tools', CLAUDE_READ_ONLY_TOOLS.join(','));
+    if (policy.tools.allow?.length)
+        args.push('--allowedTools', policy.tools.allow.join(','));
+    const denied = [...new Set([...(policy.tools.deny ?? []), ...(!nativeSubagentsAllowed(policy) ? CLAUDE_SUBAGENT_TOOLS : [])])];
+    if (denied.length)
+        args.push('--disallowedTools', denied.join(','));
+    if (policy.mcp.servers.length)
+        args.push('--mcp-config', mcpConfig(policy.mcp.servers));
+    if (!policy.mcp.inheritUserScope)
+        args.push('--strict-mcp-config');
+    if (spec.providerSessionRef)
+        args.push('--resume', spec.providerSessionRef);
+    return args;
+}
+/**
+ * Environment for the Claude process. Native sub-agents run on another model
+ * through `CLAUDE_CODE_SUBAGENT_MODEL` (verified live: a haiku parent ran a
+ * sonnet sub-agent). Claude has no per-sub-agent effort.
+ */
+export function claudeEnv(policy, base) {
+    const env = { ...base };
+    delete env.CLAUDE_CODE_SUBAGENT_MODEL;
+    if (nativeSubagentsAllowed(policy) && policy.subagentRuntime.mode === 'native' && policy.subagentRuntime.model)
+        env.CLAUDE_CODE_SUBAGENT_MODEL = policy.subagentRuntime.model;
+    return env;
+}

package/dist/agent-runtime/session/drivers/claude/driver.d.ts

@@ -0,0 +1,19 @@
+import type { DriverDescriptor } from '../../domain/types.js';
+import type { DriverEventSink, DriverFactory, DriverOpenSpec, DriverSession } from '../../ports.js';
+import { type ProcessSpawner } from '../common/process.js';
+export declare const CLAUDE_DESCRIPTOR: DriverDescriptor;
+export interface ClaudeDriverOptions {
+    binary?: string;
+    spawner?: ProcessSpawner;
+    env?: NodeJS.ProcessEnv;
+    /** Grace between SIGTERM and SIGKILL; Claude reports stopped tasks while it shuts down. */
+    terminateGraceMs?: number;
+    /** Inline system prompts longer than this go through a private temp file. */
+    maxInlineSystemPrompt?: number;
+}
+export declare class ClaudeDriverFactory implements DriverFactory {
+    private readonly options;
+    readonly descriptor: DriverDescriptor;
+    constructor(options?: ClaudeDriverOptions);
+    open(spec: DriverOpenSpec, sink: DriverEventSink): Promise<DriverSession>;
+}

package/dist/agent-runtime/session/drivers/claude/driver.js

@@ -0,0 +1,134 @@
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { spawnResidentProcess } from '../common/process.js';
+import { claudeArgs, claudeEnv } from './argv.js';
+import { ClaudeTranslator } from './translator.js';
+export const CLAUDE_DESCRIPTOR = Object.freeze({
+    id: 'claude',
+    displayName: 'Claude Code',
+    testedVersions: ['2.1.285'],
+    capabilities: Object.freeze({
+        resident: true,
+        nativeInputQueue: true,
+        subagents: 'supported',
+        subagentDisable: true,
+        subagentModel: true,
+        subagentEffort: false,
+        autonomousContinuation: true,
+        steer: true,
+        toolFiltering: true,
+        usage: Object.freeze({ costUsd: 'session-cumulative', tokens: 'per-turn' }),
+    }),
+});
+const IMAGE_TYPES = Object.freeze({ '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp' });
+function userContent(input) {
+    const files = (input.attachments ?? []).filter((item) => item.kind === 'file' || !IMAGE_TYPES[path.extname(item.path).toLowerCase()]);
+    const images = (input.attachments ?? []).filter((item) => item.kind === 'image' && IMAGE_TYPES[path.extname(item.path).toLowerCase()]);
+    const text = files.length ? `${input.text}\n\nAttached files:\n${files.map((file) => `- ${file.path}`).join('\n')}` : input.text;
+    if (images.length === 0)
+        return text;
+    return [
+        ...images.map((image) => ({ type: 'image', source: { type: 'base64', media_type: image.mimeType ?? IMAGE_TYPES[path.extname(image.path).toLowerCase()], data: readFileSync(image.path).toString('base64') } })),
+        { type: 'text', text },
+    ];
+}
+class ClaudeDriverSession {
+    process;
+    translator;
+    graceMs;
+    cleanup;
+    closing = null;
+    constructor(process, translator, graceMs, cleanup) {
+        this.process = process;
+        this.translator = translator;
+        this.graceMs = graceMs;
+        this.cleanup = cleanup;
+    }
+    async send(input) {
+        this.translator.noteInput(input.inputId);
+        const frame = {
+            type: 'user',
+            uuid: input.inputId,
+            session_id: '',
+            parent_tool_use_id: null,
+            // `next` delivers into the running turn; otherwise the CLI queues it for the next turn.
+            ...(input.delivery === 'steer' ? { priority: 'next' } : {}),
+            message: { role: 'user', content: userContent(input) },
+        };
+        if (!this.process.write(JSON.stringify(frame)))
+            throw new Error('Claude input is closed');
+    }
+    async interrupt() {
+        this.translator.noteInterrupt();
+        this.process.write(JSON.stringify({ type: 'control_request', request_id: randomUUID(), request: { subtype: 'interrupt' } }));
+    }
+    /** Claude Code exposes no per-task stop on stdin: stopping means ending the process. */
+    async stopSubagents() {
+        return 'process';
+    }
+    close(_reason) {
+        this.closing ??= (async () => {
+            this.process.endInput();
+            await this.process.terminate(this.graceMs);
+            this.cleanup();
+        })();
+        return this.closing;
+    }
+}
+export class ClaudeDriverFactory {
+    options;
+    descriptor = CLAUDE_DESCRIPTOR;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async open(spec, sink) {
+        const translator = new ClaudeTranslator();
+        let promptDir = null;
+        let systemPromptFile;
+        const maxInline = this.options.maxInlineSystemPrompt ?? (process.platform === 'win32' ? 4_000 : 64_000);
+        if (spec.systemPrompt && spec.systemPrompt.length > maxInline) {
+            promptDir = mkdtempSync(path.join(tmpdir(), 'specrails-session-'));
+            systemPromptFile = path.join(promptDir, 'system-prompt.md');
+            writeFileSync(systemPromptFile, spec.systemPrompt, { mode: 0o600 });
+        }
+        const cleanup = () => { if (promptDir)
+            rmSync(promptDir, { recursive: true, force: true }); };
+        let closed = false;
+        const spawner = this.options.spawner ?? spawnResidentProcess;
+        const child = spawner({ command: this.options.binary ?? 'claude', args: claudeArgs(spec, systemPromptFile ? { systemPromptFile } : {}), cwd: spec.cwd, env: claudeEnv(spec.policy, this.options.env ?? process.env) }, {
+            onLine: (line) => {
+                if (closed)
+                    return;
+                let frame;
+                try {
+                    frame = JSON.parse(line);
+                }
+                catch {
+                    sink({ kind: 'diagnostic', level: 'warning', code: 'provider.unparseable', message: line.slice(0, 500) });
+                    return;
+                }
+                for (const event of translator.translate(frame))
+                    sink(event);
+            },
+        });
+        const session = new ClaudeDriverSession(child, translator, this.options.terminateGraceMs ?? 5_000, cleanup);
+        let closeRequested = false;
+        void child.exited.then((exit) => {
+            cleanup();
+            // An exit we asked for is not a crash; lines printed while stopping were already delivered.
+            if (!closed && !closeRequested)
+                sink({ kind: 'process.exited', exitCode: exit.exitCode, signal: exit.signal });
+            closed = true;
+        });
+        const originalClose = session.close.bind(session);
+        session.close = async (reason) => {
+            closeRequested = true;
+            await originalClose(reason);
+            closed = true;
+        };
+        sink({ kind: 'process.started', ...(child.pid !== undefined ? { pid: child.pid } : {}) });
+        return session;
+    }
+}

package/dist/agent-runtime/session/drivers/claude/translator.d.ts

@@ -0,0 +1,40 @@
+import type { DriverEvent } from '../../ports.js';
+/**
+ * Anti-corruption layer for Claude Code `--output-format stream-json`.
+ * Deterministic and free of I/O: one wire frame in, normalized events out.
+ * Behaviour pinned by the recorded transcripts (Claude Code 2.1.285):
+ * - `command_lifecycle` = per-input receipts; the CLI serializes turns itself;
+ * - a turn runs from `system/init` to `result`; turns without a started input
+ *   are the CLI's own continuations (result `origin.kind = task-notification`);
+ * - sub-agents and their shells are `task_*` frames; their messages carry
+ *   `parent_tool_use_id`; the same task id restarts after reporting completion.
+ */
+type Frame = Record<string, unknown>;
+export declare class ClaudeTranslator {
+    private sessionRef;
+    private turnOpen;
+    private interruptRequested;
+    private readonly written;
+    private startedInputs;
+    /** tool_use id → task id of the agent that issued it (null = main agent). */
+    private readonly toolOwner;
+    private readonly toolName;
+    /** Agent/Task tool_use id → task id it became. */
+    private readonly taskByToolUse;
+    private readonly taskPhase;
+    private readonly reportedUnknown;
+    /** The driver wrote this input; its receipts and replays belong to us. */
+    noteInput(inputId: string): void;
+    noteInterrupt(): void;
+    translate(frame: Frame): DriverEvent[];
+    private system;
+    private taskStarted;
+    private phase;
+    private lifecycle;
+    private ownerOf;
+    private assistant;
+    private user;
+    private result;
+    private unknown;
+}
+export {};

package/dist/agent-runtime/session/drivers/claude/translator.js

@@ -0,0 +1,247 @@
+const TASK_PHASE = Object.freeze({
+    completed: 'idle',
+    failed: 'failed',
+    stopped: 'stopped',
+    killed: 'killed',
+});
+/** System subtypes that carry nothing the session model needs. */
+const IGNORED_SYSTEM = new Set(['thinking_tokens', 'task_summary', 'post_turn_summary', 'status', 'hook_response', 'hook_started', 'compact_boundary']);
+const IGNORED_TYPES = new Set(['rate_limit_event', 'stream_event', 'keep_alive']);
+function str(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function textOf(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content))
+        return content.map((part) => (part && typeof part === 'object' && part.type === 'text' ? String(part.text ?? '') : '')).join('');
+    return '';
+}
+export class ClaudeTranslator {
+    sessionRef = null;
+    turnOpen = false;
+    interruptRequested = false;
+    written = new Set();
+    startedInputs = [];
+    /** tool_use id → task id of the agent that issued it (null = main agent). */
+    toolOwner = new Map();
+    toolName = new Map();
+    /** Agent/Task tool_use id → task id it became. */
+    taskByToolUse = new Map();
+    taskPhase = new Map();
+    reportedUnknown = new Set();
+    /** The driver wrote this input; its receipts and replays belong to us. */
+    noteInput(inputId) { this.written.add(inputId); }
+    noteInterrupt() { if (this.turnOpen)
+        this.interruptRequested = true; }
+    translate(frame) {
+        const type = str(frame.type);
+        switch (type) {
+            case 'system': return this.system(frame);
+            case 'command_lifecycle': return this.lifecycle(frame);
+            case 'assistant': return this.assistant(frame);
+            case 'user': return this.user(frame);
+            case 'result': return this.result(frame);
+            default:
+                if (type && IGNORED_TYPES.has(type))
+                    return [];
+                return this.unknown(`type:${type ?? '<missing>'}`);
+        }
+    }
+    system(frame) {
+        const subtype = str(frame.subtype) ?? '';
+        switch (subtype) {
+            case 'init': {
+                const events = [];
+                const ref = str(frame.session_id);
+                if (ref && ref !== this.sessionRef) {
+                    this.sessionRef = ref;
+                    events.push({ kind: 'provider.ref', providerSessionRef: ref });
+                }
+                if (!this.turnOpen) {
+                    this.turnOpen = true;
+                    const inputIds = this.startedInputs;
+                    this.startedInputs = [];
+                    events.push({ kind: 'turn.started', trigger: inputIds.length > 0 ? 'input' : 'continuation', inputIds });
+                }
+                return events;
+            }
+            case 'task_started': return this.taskStarted(frame);
+            case 'task_progress': {
+                const taskId = str(frame.task_id);
+                const usage = frame.usage;
+                if (!taskId || !this.taskPhase.has(taskId))
+                    return [];
+                return [{
+                        kind: 'subagent.usage',
+                        subagentId: taskId,
+                        usage: { totalTokens: num(usage?.total_tokens) ?? null },
+                        ...(num(usage?.tool_uses) !== undefined ? { toolUses: num(usage?.tool_uses) } : {}),
+                        ...(num(usage?.duration_ms) !== undefined ? { durationMs: num(usage?.duration_ms) } : {}),
+                    }];
+            }
+            case 'task_updated': {
+                const taskId = str(frame.task_id);
+                const status = str(frame.patch?.status);
+                return taskId && status ? this.phase(taskId, status) : [];
+            }
+            case 'task_notification': {
+                const taskId = str(frame.task_id);
+                const status = str(frame.status);
+                if (!taskId || !this.taskPhase.has(taskId))
+                    return [];
+                const usage = frame.usage;
+                const summary = str(frame.summary);
+                return [
+                    ...(usage ? [{ kind: 'subagent.usage', subagentId: taskId, usage: { totalTokens: num(usage.total_tokens) ?? null }, ...(num(usage.tool_uses) !== undefined ? { toolUses: num(usage.tool_uses) } : {}), ...(num(usage.duration_ms) !== undefined ? { durationMs: num(usage.duration_ms) } : {}) }] : []),
+                    ...(status === 'completed' && summary ? [{ kind: 'subagent.result', subagentId: taskId, summary }] : []),
+                    ...(status ? this.phase(taskId, status) : []),
+                ];
+            }
+            case 'background_tasks_changed': {
+                const tasks = Array.isArray(frame.tasks) ? frame.tasks : null;
+                if (!tasks)
+                    return [];
+                return [{ kind: 'roster', liveSubagentIds: tasks.filter((task) => task?.ambient !== true).map((task) => str(task?.task_id)).filter((id) => !!id) }];
+            }
+            default:
+                return IGNORED_SYSTEM.has(subtype) ? [] : this.unknown(`system:${subtype}`);
+        }
+    }
+    taskStarted(frame) {
+        const taskId = str(frame.task_id);
+        if (!taskId)
+            return [];
+        const toolUseId = str(frame.tool_use_id);
+        if (toolUseId)
+            this.taskByToolUse.set(toolUseId, taskId);
+        const restarted = this.taskPhase.has(taskId);
+        this.taskPhase.set(taskId, 'running');
+        const isShell = frame.task_type === 'local_bash';
+        const parentId = toolUseId ? this.toolOwner.get(toolUseId) ?? null : null;
+        const prompt = str(frame.prompt);
+        return [{
+                kind: 'subagent.started',
+                subagentId: taskId,
+                parentId,
+                agentKind: frame.is_backgrounded === true ? 'background' : 'foreground',
+                agentType: isShell ? 'shell' : str(frame.subagent_type) ?? 'agent',
+                description: str(frame.description) ?? (isShell ? 'Background command' : 'Sub-agent'),
+                ...(prompt && !restarted ? { prompt } : {}),
+            }];
+    }
+    phase(taskId, status) {
+        const phase = TASK_PHASE[status];
+        if (!phase || !this.taskPhase.has(taskId) || this.taskPhase.get(taskId) === phase)
+            return [];
+        this.taskPhase.set(taskId, phase);
+        return [{ kind: 'subagent.phase', subagentId: taskId, phase }];
+    }
+    lifecycle(frame) {
+        const inputId = str(frame.command_uuid);
+        const state = str(frame.state);
+        if (!inputId || !this.written.has(inputId))
+            return [];
+        if (state === 'started' && !this.turnOpen)
+            this.startedInputs.push(inputId);
+        if (state === 'queued' || state === 'started' || state === 'completed')
+            return [{ kind: 'input.receipt', inputId, state }];
+        if (state === 'failed' || state === 'rejected' || state === 'cancelled')
+            return [{ kind: 'input.receipt', inputId, state: 'rejected', reason: state }];
+        return [];
+    }
+    ownerOf(frame) {
+        const parent = str(frame.parent_tool_use_id);
+        if (!parent)
+            return null;
+        return this.taskByToolUse.get(parent);
+    }
+    assistant(frame) {
+        const owner = this.ownerOf(frame);
+        if (owner === undefined)
+            return this.unknown('assistant:unattributed-parent');
+        const content = (frame.message?.content ?? []);
+        const events = [];
+        for (const block of Array.isArray(content) ? content : []) {
+            if (block.type === 'text' && typeof block.text === 'string' && block.text) {
+                events.push(owner === null
+                    ? { kind: 'turn.output', channel: 'text', delta: block.text }
+                    : { kind: 'subagent.output', subagentId: owner, channel: 'text', delta: block.text });
+            }
+            else if (block.type === 'thinking' && typeof block.thinking === 'string' && block.thinking && owner === null) {
+                events.push({ kind: 'turn.output', channel: 'thinking', delta: block.thinking });
+            }
+            else if (block.type === 'tool_use') {
+                const id = str(block.id);
+                const name = str(block.name) ?? 'tool';
+                if (!id)
+                    continue;
+                this.toolOwner.set(id, owner);
+                this.toolName.set(id, name);
+                const tool = { toolUseId: id, name, phase: 'started', input: block.input };
+                events.push(owner === null ? { kind: 'turn.tool', ...tool } : { kind: 'subagent.output', subagentId: owner, channel: 'tool', tool });
+            }
+        }
+        return events;
+    }
+    user(frame) {
+        const uuid = str(frame.uuid);
+        if (uuid && this.written.has(uuid))
+            return []; // replay of our own input
+        const owner = this.ownerOf(frame);
+        const content = frame.message?.content;
+        if (!Array.isArray(content))
+            return [];
+        const events = [];
+        for (const block of content) {
+            if (block.type !== 'tool_result')
+                continue;
+            const id = str(block.tool_use_id);
+            if (!id)
+                continue;
+            const issuer = this.toolOwner.has(id) ? this.toolOwner.get(id) : owner ?? null;
+            const tool = { toolUseId: id, name: this.toolName.get(id) ?? 'tool', phase: 'completed', output: textOf(block.content).slice(0, 16_384), ...(block.is_error === true ? { isError: true } : {}) };
+            events.push(issuer === null ? { kind: 'turn.tool', ...tool } : { kind: 'subagent.output', subagentId: issuer, channel: 'tool', tool });
+        }
+        return events;
+    }
+    result(frame) {
+        const origin = frame.origin?.kind;
+        const text = str(frame.result) ?? '';
+        if (!this.turnOpen) {
+            // An orphan notification on resume (num_turns 0, empty) carries nothing.
+            if (origin === 'task-notification')
+                return [];
+            return this.unknown('result:without-turn');
+        }
+        this.turnOpen = false;
+        const interrupted = this.interruptRequested;
+        this.interruptRequested = false;
+        const failed = frame.is_error === true || (str(frame.subtype) !== undefined && frame.subtype !== 'success');
+        const usage = frame.usage;
+        const modelUsage = frame.modelUsage;
+        return [{
+                kind: 'turn.completed',
+                status: interrupted ? 'stopped' : failed ? 'failed' : 'completed',
+                text,
+                ...(failed && !interrupted ? { error: text || str(frame.subtype) || 'Provider reported an error' } : {}),
+                usage: {
+                    costUsd: num(frame.total_cost_usd) ?? null,
+                    inputTokens: num(usage?.input_tokens) ?? null,
+                    outputTokens: num(usage?.output_tokens) ?? null,
+                    cacheReadTokens: num(usage?.cache_read_input_tokens) ?? null,
+                    cacheWriteTokens: num(usage?.cache_creation_input_tokens) ?? null,
+                    model: modelUsage ? Object.keys(modelUsage)[0] ?? null : null,
+                },
+            }];
+    }
+    unknown(code) {
+        if (this.reportedUnknown.has(code))
+            return [];
+        this.reportedUnknown.add(code);
+        return [{ kind: 'diagnostic', level: 'info', code: 'provider.unknown', message: `Unrecognised Claude frame (${code})` }];
+    }
+}