@meistrari/agent-core 0.0.0 → 0.1.1

package/src/agents/claude/claude-provider.ts

@@ -0,0 +1,191 @@
+import type { Options, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk'
+import type { ClaudeModelId } from '../../protocol'
+import type { AgentOperationOptions } from '../agent-operation'
+import type { AgentProvider, AgentSessionOpenInput, AgentSessionResumeInput } from '../agent-provider'
+import type { AgentTool } from '../agent-tool'
+import type { InstructionComposer } from '../instructions'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { query as queryClaude } from '@anthropic-ai/claude-agent-sdk'
+import { claudeModelIdSchema } from '../../protocol'
+import { AgentRunStateError } from '../agent-runtime-error'
+import { selectAgentTools } from '../agent-tool'
+import { emptyInstructionComposer } from '../instructions'
+import { removeUndefined } from '../normalize'
+import { UserInputRequestStore, userInputRequestStoreRootFromTranscriptPath } from '../user-input-request'
+import { createClaudeEventMapperState } from './claude-event-mapper'
+import { ClaudeRun } from './claude-run'
+import { claudeAllowedToolNames, claudeToolActorHooks, createClaudeToolRuntimeRef, toClaudeMcpServers } from './claude-tool-mapper'
+
+export interface ClaudeProviderConfig {
+    tools?: readonly AgentTool[]
+    executable?: string
+    environment?: Record<string, string | undefined>
+    instructions?: InstructionComposer
+}
+
+export class ClaudeProvider implements AgentProvider<'claude'> {
+    readonly id = 'claude' as const
+    private readonly tools: readonly AgentTool[]
+    private readonly executable: string | undefined
+    private readonly environment: Record<string, string | undefined>
+    private readonly instructions: InstructionComposer
+
+    private constructor(config: ClaudeProviderConfig) {
+        this.tools = config.tools ?? []
+        this.executable = config.executable
+        this.environment = config.environment ?? {}
+        this.instructions = config.instructions ?? emptyInstructionComposer
+    }
+
+    static create(config: ClaudeProviderConfig = {}): ClaudeProvider {
+        return new ClaudeProvider(config)
+    }
+
+    async openSession(input: AgentSessionOpenInput<'claude'>, options: AgentOperationOptions = {}): Promise<ClaudeRun> {
+        // Prebind a caller-minted UUID (Options.sessionId) so the binding is known before any input.
+        const providerSessionId = crypto.randomUUID()
+        return await this.openRun({ input, session: { sessionId: providerSessionId }, expectedSessionId: providerSessionId, operationOptions: options })
+    }
+
+    async resumeSession(input: AgentSessionResumeInput<'claude'>, options: AgentOperationOptions = {}): Promise<ClaudeRun> {
+        return await this.openRun({ input, session: { resume: input.providerSessionId }, expectedSessionId: input.providerSessionId, operationOptions: options })
+    }
+
+    private async openRun(params: {
+        input: AgentSessionOpenInput<'claude'> | AgentSessionResumeInput<'claude'>
+        session: { sessionId?: string, resume?: string }
+        expectedSessionId: string
+        operationOptions: AgentOperationOptions
+    }): Promise<ClaudeRun> {
+        const { input, session, expectedSessionId, operationOptions } = params
+        operationOptions.signal?.throwIfAborted()
+        const abortController = new AbortController()
+        operationOptions.signal?.addEventListener('abort', () => abortController.abort(), { once: true })
+        // Lifecycle applies no user input: the stream stays empty until the run receives commands.
+        const inputQueue = createInputQueue()
+        const configDir = this.environment.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude')
+        const tools = selectAgentTools(this.tools, input.tools)
+        const state = createClaudeEventMapperState()
+        const runtime = createClaudeToolRuntimeRef({ turnId: () => state.currentTurnId })
+        const sdkOptions: Options = removeUndefined({
+            abortController,
+            cwd: input.cwd,
+            env: this.environment,
+            model: input.model,
+            thinking: { type: 'adaptive', display: 'summarized' },
+            effort: input.reasoningEffort,
+            sessionId: session.sessionId,
+            resume: session.resume,
+            includePartialMessages: true,
+            forwardSubagentText: true,
+            agentProgressSummaries: true,
+            permissionMode: 'bypassPermissions',
+            allowDangerouslySkipPermissions: true,
+            tools: { type: 'preset', preset: 'claude_code' },
+            systemPrompt: { type: 'preset', preset: 'claude_code', append: this.instructions({ provider: 'claude', tools }) },
+            disallowedTools: ['AskUserQuestion', 'EnterPlanMode', 'ExitPlanMode', 'NotebookEdit', 'EnterWorktree', 'ExitWorktree'],
+            mcpServers: toClaudeMcpServers({
+                tools,
+                runtime,
+                signal: abortController.signal,
+            }),
+            allowedTools: ['Bash', ...claudeAllowedToolNames(tools)],
+            hooks: claudeToolActorHooks(tools),
+            pathToClaudeCodeExecutable: this.executable,
+        })
+
+        const query = queryClaude({ prompt: inputQueue, options: sdkOptions })
+        try {
+            // Binding metadata comes from pre-input facts only: the live runtime emits system/init
+            // only after the first user message, so the run validates identity/config on the first
+            // input (init barrier). Observed runtime configuration arrives via session.started /
+            // session.configured after that validation.
+            const transcriptPath = join(configDir, 'projects', encodeClaudeProjectPath(input.cwd), `${expectedSessionId}.jsonl`)
+            const metadata = {
+                provider: 'claude' as const,
+                sessionId: input.sessionId,
+                providerSessionId: expectedSessionId,
+                cwd: input.cwd,
+                model: firstClaudeModelId(input.model),
+                transcriptPath,
+            }
+            const userInputRequests = await UserInputRequestStore.open({
+                sessionId: metadata.sessionId,
+                rootDir: userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
+            })
+
+            const run = new ClaudeRun({
+                metadata,
+                query,
+                userInputRequests,
+                input: inputQueue,
+                eventMapperState: state,
+                init: {
+                    expectedSessionId,
+                    requestedModel: input.model,
+                    reasoningEffort: input.reasoningEffort,
+                    environment: this.environment,
+                },
+            })
+            runtime.attach({
+                metadata: run.metadata,
+                requestUserInput: async request => await run.requestUserInput(request),
+            })
+            run.begin()
+            return run
+        }
+        catch (error) {
+            query.close()
+            inputQueue.close()
+            throw error
+        }
+    }
+}
+
+function firstClaudeModelId(...values: Array<string | null | undefined>): ClaudeModelId | undefined {
+    for (const value of values) {
+        const parsed = claudeModelIdSchema.safeParse(value)
+        if (parsed.success)
+            return parsed.data
+    }
+    return undefined
+}
+
+function createInputQueue(): AsyncIterable<SDKUserMessage> & { push: (message: SDKUserMessage) => Promise<void>, close: () => void } {
+    const items: SDKUserMessage[] = []
+    const waiters: Array<(value: IteratorResult<SDKUserMessage>) => void> = []
+    let closed = false
+
+    return {
+        async push(message) {
+            // Never drop input silently: a closed stream means the run has ended.
+            if (closed)
+                throw new AgentRunStateError({ message: 'Claude input stream is closed.' })
+            const waiter = waiters.shift()
+            if (waiter)
+                waiter({ value: message, done: false })
+            else items.push(message)
+        },
+        close() {
+            closed = true
+            for (const waiter of waiters.splice(0)) waiter({ value: undefined, done: true })
+        },
+        [Symbol.asyncIterator]() {
+            return {
+                async next(): Promise<IteratorResult<SDKUserMessage>> {
+                    const item = items.shift()
+                    if (item)
+                        return await Promise.resolve({ value: item, done: false })
+                    if (closed)
+                        return await Promise.resolve({ value: undefined, done: true })
+                    return await new Promise(resolve => waiters.push(resolve))
+                },
+            }
+        },
+    }
+}
+
+function encodeClaudeProjectPath(cwd: string): string {
+    return cwd.replaceAll('/', '-')
+}

package/src/agents/claude/claude-run.ts

@@ -0,0 +1,468 @@
+import type { Query, SDKMessage, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk'
+import type {
+    AgentError,
+    AgentReasoningEffort,
+    AgentRunMetadata,
+    InterruptAgentCommand,
+    RespondUserInputAgentCommand,
+    SendPromptCommand,
+    StopAgentCommand,
+} from '../../protocol'
+import type { AgentEventDraft } from '../agent-event-stream'
+import type { AgentOperationOptions } from '../agent-operation'
+import type { AgentPromptAcceptance, AgentRun, AgentUserInputSubmission } from '../agent-run'
+import type { UserInputRequestInput, UserInputRequestStore } from '../user-input-request'
+import type { ClaudeEventMapperState } from './claude-event-mapper'
+import z from 'zod'
+import { serializeAgentError } from '../agent-error-serializer'
+import { AgentEventStream } from '../agent-event-stream'
+import { AgentDeliveryUnknownError, AgentNotAcceptedError, AgentProviderMetadataError, AgentProviderProtocolError, AgentRunStateError } from '../agent-runtime-error'
+import { sessionConfiguredEvent } from '../agent-session-events'
+import { deriveMessageId } from '../message-id'
+import { mapClaudeUserMessage, toClaudeUserMessage } from './claude-command-mapper'
+import { mapClaudeMessage } from './claude-event-mapper'
+
+// The ONE long-lived SDK input stream created with the query. SDK 0.3.207 Query.streamInput ends
+// stdin after any finite iterable and the transport silently drops later writes, so every user
+// message must go through this original stream instead.
+interface ClaudeInputStream {
+    push: (message: SDKUserMessage) => Promise<void>
+    close: () => void
+}
+
+// Live runtime fact (CLI 2.1.207): system/init is emitted only after the first user message is
+// consumed. The run therefore validates identity/config on the first input instead of at open.
+interface ClaudeInitExpectation {
+    expectedSessionId: string
+    requestedModel?: string
+    reasoningEffort?: AgentReasoningEffort
+    environment: Record<string, string | undefined>
+}
+
+type ClaudeInitMessage = Extract<SDKMessage, { type: 'system', subtype: 'init' }>
+interface ClaudeCommandLifecycleMessage {
+    type: 'command_lifecycle'
+}
+
+// The Claude prompt-acceptance receipt is a pinned, live-verified but undocumented CLI frame
+// (SDK 0.3.207 / bundled CLI 2.1.207): it is absent from the SDK's exported SDKMessage union,
+// and its exact shape below was proven by scripts/smoke/claude-command-acceptance-probe.ts —
+// which must be rerun before any SDK/CLI upgrade. On the pinned runtime, any shape or state
+// deviation is provider protocol drift and fails the run closed. The state enum mirrors the pinned
+// CLI's embedded schema exactly: `queued`/`started`/`completed` are positive; `cancelled`
+// (steered-over/aborted) and `discarded` (session ended with the command still queued) are
+// schema-valid NEGATIVE terminals that never mean acceptance.
+const commandLifecycleFrameSchema = z.strictObject({
+    type: z.literal('command_lifecycle'),
+    command_uuid: z.uuid(),
+    session_id: z.uuid(),
+    state: z.enum(['queued', 'started', 'completed', 'cancelled', 'discarded']),
+    uuid: z.uuid(),
+})
+
+interface AcceptanceWaiter {
+    promise: Promise<void>
+    resolve: () => void
+    reject: (error: unknown) => void
+}
+
+function interruptTargetsTurn(interrupt: ClaudeEventMapperState['interrupt'], turnId: string): boolean {
+    return interrupt.status !== 'none' && interrupt.turnId === turnId
+}
+
+interface ClaudeRunInput {
+    metadata: AgentRunMetadata
+    query: Query
+    userInputRequests: UserInputRequestStore
+    input: ClaudeInputStream
+    eventMapperState: ClaudeEventMapperState
+    init: ClaudeInitExpectation
+}
+
+export class ClaudeRun implements AgentRun {
+    readonly events: AgentEventStream
+    readonly metadata: AgentRunMetadata
+    private readonly query: Query
+    private readonly userInputRequests: UserInputRequestStore
+    private readonly input: ClaudeInputStream
+    private readonly eventMapperState: ClaudeEventMapperState
+    private readonly init: ClaudeInitExpectation
+    private readonly initialization: Promise<void>
+    private initializationResolve: () => void = () => undefined
+    private initializationReject: (error: unknown) => void = () => undefined
+    private initialized = false
+    private firstInputPushed = false
+    private finished = false
+    private interruptRequest?: { turnId: string, promise: Promise<void> }
+    private readonly acceptanceWaiters = new Map<string, AcceptanceWaiter>()
+
+    constructor({ metadata, query, userInputRequests, input, eventMapperState, init }: ClaudeRunInput) {
+        this.metadata = metadata
+        this.query = query
+        this.userInputRequests = userInputRequests
+        this.input = input
+        this.eventMapperState = eventMapperState
+        this.init = init
+        this.initialization = new Promise<void>((resolve, reject) => {
+            this.initializationResolve = resolve
+            this.initializationReject = reject
+        })
+        // The barrier can reject with nothing awaiting it (pre-init EOF/stop); keep that handled.
+        this.initialization.catch(() => undefined)
+        this.events = new AgentEventStream({
+            provider: 'claude',
+            sessionId: metadata.sessionId,
+            providerSessionId: metadata.providerSessionId,
+        })
+    }
+
+    // Starts the single background query consumer. command_lifecycle frames are the acceptance
+    // receipt: they are strictly validated and ROUTED to settle the matching sendPrompt waiter
+    // (never skipped, never mapped to an AgentEvent), including the first input's queued frame that
+    // legitimately precedes system/init. PRE_INIT is otherwise strict: the next non-lifecycle
+    // message must be a matching system/init, and the run's own session lifecycle AgentEvents
+    // (session.started/configured/state) are emitted only after that init validation.
+    begin(): void {
+        void this.consume()
+    }
+
+    pushEvent(draft: AgentEventDraft): void {
+        if (this.finished)
+            return
+        const decorated = this.userInputRequests.decorateTurnEnded(draft)
+        if (decorated.type === 'session.state.changed' && decorated.payload.state === 'idle' && this.userInputRequests.shouldHoldIdle()) {
+            this.events.push({ type: 'session.state.changed', payload: { state: 'waiting_for_user_input' } })
+            return
+        }
+        this.events.push(decorated)
+    }
+
+    async requestUserInput(input: UserInputRequestInput): Promise<{ requestId: string }> {
+        this.assertRunning()
+        const request = this.userInputRequests.create(input)
+        this.pushEvent(request.event)
+        return { requestId: request.requestId }
+    }
+
+    async prepareWorkspace(options: AgentOperationOptions = {}): Promise<void> {
+        options.signal?.throwIfAborted()
+    }
+
+    // Claude discovers repository guidance from the filesystem; there is no provider-side root registry.
+    async addWorkspaceRepositoryRoot(_root: string, options: AgentOperationOptions = {}): Promise<void> {
+        options.signal?.throwIfAborted()
+    }
+
+    async sendPrompt(command: SendPromptCommand, options: AgentOperationOptions = {}): Promise<AgentPromptAcceptance> {
+        this.assertCommandTargetsRun(command)
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        const input = { prompt: command.prompt, mode: command.mode, commandId: command.commandId, origin: command.origin, author: command.author, senderContext: options.senderContext }
+        const message = await mapClaudeUserMessage(input, options.inputAttachmentPreparation)
+        options.signal?.throwIfAborted()
+        // Register before the push: the CLI's queued receipt can outrun the local push resolution,
+        // and a receipt with no registered waiter would be lost.
+        const clientMessageId = deriveMessageId(command.commandId)
+        const receipt = this.registerAcceptanceWaiter(clientMessageId)
+        try {
+            await this.deliverInput(message)
+            // `submitted` requires the provider's positive acceptance receipt — the pinned
+            // command_lifecycle frame matching this command's derived uuid and this session —
+            // in addition to delivery (and, for the first input, validated init identity).
+            // Local queue push, transport write, and init alone are never acceptance. No timeout:
+            // provider close/error settles the wait as delivery-unknown.
+            await receipt.promise
+        }
+        finally {
+            this.acceptanceWaiters.delete(clientMessageId)
+        }
+        return { kind: 'submitted' }
+    }
+
+    async respondUserInput(command: RespondUserInputAgentCommand, options: AgentOperationOptions = {}): Promise<AgentUserInputSubmission> {
+        this.assertCommandTargetsRun(command)
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        const resolved = this.userInputRequests.resolve(command)
+        if (!resolved)
+            return 'already_delivered'
+        // Deliver first: on a prebound resume this is the run's first input, and the resolved
+        // event must not precede the lifecycle events the init barrier emits.
+        await this.deliverInput(toClaudeUserMessage({ prompt: resolved.prompt, mode: 'next', commandId: command.commandId }))
+        if (resolved.event)
+            this.pushEvent(resolved.event)
+        this.userInputRequests.markDelivered(command.requestId)
+        return 'submitted'
+    }
+
+    async interrupt(command: InterruptAgentCommand, options: AgentOperationOptions = {}): Promise<void> {
+        this.assertCommandTargetsRun(command)
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        const turnId = this.eventMapperState.currentTurnId
+        if (!turnId)
+            return
+        if (this.eventMapperState.interrupt.status === 'accepted' && this.eventMapperState.interrupt.turnId === turnId)
+            return
+        if (this.interruptRequest?.turnId === turnId)
+            return await this.interruptRequest.promise
+
+        const promise = this.requestInterrupt(turnId)
+        this.interruptRequest = { turnId, promise }
+        try {
+            await promise
+        }
+        finally {
+            if (this.interruptRequest?.promise === promise)
+                this.interruptRequest = undefined
+        }
+    }
+
+    private async requestInterrupt(turnId: string): Promise<void> {
+        this.eventMapperState.interrupt = { status: 'requesting', turnId }
+        try {
+            // `still_queued` describes future Claude inputs; foreground-turn interruption does not cancel them.
+            await this.query.interrupt()
+            if (this.eventMapperState.interrupt.status === 'requesting' && this.eventMapperState.interrupt.turnId === turnId)
+                this.eventMapperState.interrupt = { status: 'accepted', turnId }
+        }
+        catch (error) {
+            if (interruptTargetsTurn(this.eventMapperState.interrupt, turnId))
+                this.eventMapperState.interrupt = { status: 'none' }
+            throw error
+        }
+    }
+
+    async stop(command: StopAgentCommand, options: AgentOperationOptions = {}): Promise<void> {
+        this.assertCommandTargetsRun(command)
+        options.signal?.throwIfAborted()
+        if (this.finished)
+            return
+        this.events.push({ type: 'session.state.changed', payload: { state: 'stopping' } })
+        if (!this.initialized)
+            this.initializationReject(new AgentRunStateError({ message: 'Claude run stopped before initialization.' }))
+        this.query.close()
+        this.finish('stopped')
+    }
+
+    finish(reason: 'completed' | 'stopped' | 'interrupted' | 'failed', error?: AgentError): void {
+        if (this.finished)
+            return
+        this.finished = true
+        // The run ends before pending inputs saw their acceptance receipt: each may already be in
+        // the CLI stream, so their outcome is delivery-unknown — never a hang, retry, or terminal.
+        for (const waiter of this.acceptanceWaiters.values()) {
+            waiter.reject(new AgentDeliveryUnknownError({
+                message: `Claude run ended (${reason}) before the input's acceptance receipt was observed.`,
+            }))
+        }
+        this.acceptanceWaiters.clear()
+        this.events.push({ type: 'session.ended', payload: error ? { reason, error } : { reason } })
+        this.events.push({ type: 'session.state.changed', payload: { state: reason === 'failed' ? 'failed' : 'stopped' } })
+        this.events.end()
+    }
+
+    // One pending acceptance per derived command uuid; the promise is pre-observed so a rejection
+    // while the caller is still awaiting delivery/init can never become an unhandled rejection.
+    private registerAcceptanceWaiter(clientMessageId: string): AcceptanceWaiter {
+        if (this.finished)
+            throw new AgentRunStateError({ message: 'Claude run has stopped.' })
+        if (this.acceptanceWaiters.has(clientMessageId))
+            throw new AgentRunStateError({ message: 'A prompt with this command id is already awaiting acceptance.' })
+        let resolve: () => void = () => undefined
+        let reject: (error: unknown) => void = () => undefined
+        const promise = new Promise<void>((promiseResolve, promiseReject) => {
+            resolve = promiseResolve
+            reject = promiseReject
+        })
+        promise.catch(() => undefined)
+        const waiter: AcceptanceWaiter = { promise, resolve, reject }
+        this.acceptanceWaiters.set(clientMessageId, waiter)
+        return waiter
+    }
+
+    // Strict pinned-runtime boundary for the undocumented receipt frame: shape/state deviation and
+    // session identity mismatch are provider protocol drift and fail the run closed. `cancelled`
+    // (a steered-over/aborted command) and `discarded` (the session ended with the command still
+    // queued) are valid observed states but NEGATIVE terminals — never a positive acceptance, so
+    // they reject any pending waiter as delivery-unknown so command processing can advance.
+    // Valid positive frames without a pending
+    // waiter are internal lifecycle for already-settled or non-prompt inputs and are ignored.
+    private settleAcceptance(frame: ClaudeCommandLifecycleMessage): void {
+        const parsed = commandLifecycleFrameSchema.safeParse(frame)
+        if (!parsed.success) {
+            throw new AgentProviderProtocolError({
+                message: 'Claude emitted a command_lifecycle frame with an unrecognized shape or state.',
+                cause: parsed.error,
+            })
+        }
+        if (parsed.data.session_id !== this.metadata.providerSessionId) {
+            throw new AgentProviderProtocolError({
+                message: 'Claude command_lifecycle frame targets a different session.',
+                details: { expected: this.metadata.providerSessionId, actual: parsed.data.session_id },
+            })
+        }
+        if (parsed.data.state === 'cancelled' || parsed.data.state === 'discarded') {
+            this.acceptanceWaiters.get(parsed.data.command_uuid)?.reject(new AgentDeliveryUnknownError({
+                message: `Claude command ended as ${parsed.data.state} before acceptance was observed.`,
+            }))
+            return
+        }
+        this.acceptanceWaiters.get(parsed.data.command_uuid)?.resolve()
+    }
+
+    // Exactly one message may enter the stream before init: the first input wakes the CLI and then
+    // awaits identity/config validation; a concurrent input waits for the shared barrier first.
+    private async deliverInput(message: SDKUserMessage): Promise<void> {
+        if (this.initialized) {
+            await this.pushOwnedStream(message)
+            return
+        }
+        if (!this.firstInputPushed) {
+            // Claim the slot before the push so a concurrent input waits on the barrier, but
+            // release it on failure: the owned queue rejects before enqueue, so a failed first
+            // push provably wrote nothing and the next input may claim the slot again.
+            this.firstInputPushed = true
+            try {
+                await this.pushOwnedStream(message)
+            }
+            catch (error) {
+                this.firstInputPushed = false
+                throw error
+            }
+            try {
+                await this.initialization
+            }
+            catch (error) {
+                // The message already entered the CLI stream, so an init failure cannot prove
+                // non-delivery: retrying could duplicate the input.
+                throw new AgentDeliveryUnknownError({
+                    message: 'Claude initialization failed after the first input entered the stream.',
+                    cause: error,
+                })
+            }
+            return
+        }
+        try {
+            await this.initialization
+        }
+        catch (error) {
+            // This input was never written: the barrier failed while it waited (proven not accepted).
+            throw new AgentNotAcceptedError({
+                message: 'Claude initialization failed before this input was written.',
+                recovery: { kind: 'retry', reason: 'provider_initialization_failed' },
+                cause: error,
+            })
+        }
+        await this.pushOwnedStream(message)
+    }
+
+    // The owned input queue rejects synchronously before enqueue when the stream is closed, so a
+    // rejected push is proven non-delivery and safe to retry against a fresh run.
+    private async pushOwnedStream(message: SDKUserMessage): Promise<void> {
+        try {
+            await this.input.push(message)
+        }
+        catch (error) {
+            if (error instanceof AgentRunStateError) {
+                throw new AgentNotAcceptedError({
+                    message: 'Claude input stream is closed; the input was not written.',
+                    recovery: { kind: 'retry', reason: 'provider_stream_closed' },
+                    cause: error,
+                })
+            }
+            throw error
+        }
+    }
+
+    private async consume(): Promise<void> {
+        try {
+            for await (const raw of this.query) {
+                const message = raw as SDKMessage | ClaudeCommandLifecycleMessage
+                // Acceptance receipts are routed before PRE_INIT and normal mapping: the first
+                // input's queued frame legitimately precedes system/init.
+                if (message.type === 'command_lifecycle') {
+                    this.settleAcceptance(message)
+                    continue
+                }
+                if (!this.initialized) {
+                    this.completeInitialization(message)
+                    continue
+                }
+                for (const draft of mapClaudeMessage(message, this.eventMapperState)) this.pushEvent(draft)
+            }
+            // An intentional stop already finalized the run; the ended stream is expected then.
+            if (this.finished)
+                return
+            if (!this.initialized) {
+                throw new AgentProviderProtocolError({ message: 'Claude SDK ended before emitting system init.' })
+            }
+            this.finish('completed')
+        }
+        catch (error) {
+            this.failRun(error)
+        }
+        finally {
+            this.input.close()
+        }
+    }
+
+    private completeInitialization(message: SDKMessage): void {
+        if (message.type !== 'system' || message.subtype !== 'init') {
+            throw new AgentProviderProtocolError({ message: 'Claude SDK emitted an unexpected message before system init.' })
+        }
+        const init: ClaudeInitMessage = message
+        if (!init.session_id) {
+            throw new AgentProviderMetadataError({ message: 'Claude SDK init did not include session_id.', details: { provider: 'claude' } })
+        }
+        if (init.session_id !== this.init.expectedSessionId) {
+            throw new AgentProviderProtocolError({
+                message: 'Claude SDK init session_id does not match the requested session.',
+                details: { expected: this.init.expectedSessionId, actual: init.session_id },
+            })
+        }
+        const effectiveModel = init.model ?? this.init.requestedModel
+        if (!effectiveModel) {
+            throw new AgentProviderMetadataError({ message: 'Claude SDK init did not include model.', details: { provider: 'claude' } })
+        }
+
+        this.pushEvent({ type: 'session.started', payload: this.metadata })
+        this.pushEvent(sessionConfiguredEvent({
+            model: effectiveModel,
+            cwd: init.cwd ?? this.metadata.cwd,
+            reasoningEffort: this.init.reasoningEffort,
+            toolNames: init.tools,
+            environment: this.init.environment,
+        }))
+        this.pushEvent({ type: 'session.state.changed', payload: { state: 'ready' } })
+        for (const draft of mapClaudeMessage(init, this.eventMapperState)) this.pushEvent(draft)
+        this.initialized = true
+        this.initializationResolve()
+    }
+
+    private failRun(error: unknown): void {
+        if (this.finished)
+            return
+        const agentError = serializeAgentError(error)
+        if (!this.initialized) {
+            // Pre-init failure: the first-input promise must reject typed instead of hanging.
+            this.initializationReject(error)
+            this.query.close()
+            this.finish('failed', agentError)
+            return
+        }
+        this.pushEvent({ type: 'error', payload: { message: agentError.message, fatal: true, source: 'runtime', error: agentError } })
+        this.finish('failed', agentError)
+    }
+
+    private assertRunning(): void {
+        if (this.finished)
+            throw new AgentRunStateError({ message: 'Claude run has stopped.' })
+    }
+
+    private assertCommandTargetsRun(command: { provider: string, sessionId: string, providerSessionId: string }): void {
+        if (command.provider !== 'claude' || command.sessionId !== this.metadata.sessionId || command.providerSessionId !== this.metadata.providerSessionId) {
+            throw new AgentRunStateError({ message: 'Command does not target this Claude run.' })
+        }
+    }
+}