@meistrari/agent-core 0.2.0-experimental.1 → 0.2.0-experimental.3

package/src/agents/claude/claude-event-mapper.ts

@@ -2,7 +2,7 @@ import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk'
 import type { TaskCreateInput, TaskCreateOutput, TaskGetInput, TaskGetOutput, TaskListInput, TaskListOutput, TaskUpdateInput, TaskUpdateOutput } from '@anthropic-ai/claude-agent-sdk/sdk-tools'
 import type { MessageParam } from '@anthropic-ai/sdk/resources'
 import type { BetaMessage, BetaRawMessageStreamEvent, BetaUsage } from '@anthropic-ai/sdk/resources/beta/messages/messages'
-import type { AgentError, AgentEventActor, AgentUsage, JsonValue } from '../../protocol'
+import type { AgentContextSnapshot, AgentError, AgentEventActor, AgentToolContent, AgentUsage, JsonValue } from '../../protocol'
 import type { AgentWorkObservation } from '../../protocol/agent-work'
 import type { AgentEventDraft } from '../agent-event-stream'
 import { randomUUID } from 'node:crypto'
@@ -12,7 +12,9 @@ import { canonicalToolName } from '../../protocol/agent-tool-name'
 import { agentWorkStatusSchema } from '../../protocol/agent-work'
 import { createRuntimeTurnId } from '../agent-id'
 import { AgentProviderProtocolError } from '../agent-runtime-error'
+import { isJsonObject, jsonToolContent, mcpToolContent, ownJsonSlot } from '../mcp-tool-content'
 import { optionalNonEmpty, removeUndefined } from '../normalize'
+import { claudeFileChangeText } from './claude-file-change'
 import { CLAUDE_AGENT_TOOL_SERVER } from './claude-tool-mapper'
 
 type UserContentBlock = Exclude<MessageParam['content'], string>[number]
@@ -23,6 +25,18 @@ type ClaudeTaskStartedMessage = Extract<SDKMessage, { type: 'system', subtype: '
 type ClaudeTaskProgressMessage = Extract<SDKMessage, { type: 'system', subtype: 'task_progress' }>
 type ClaudeTaskNotificationMessage = Extract<SDKMessage, { type: 'system', subtype: 'task_notification' }>
 type ClaudeUserMessage = Extract<SDKMessage, { type: 'user' }>
+type ClaudeRateLimitInfo = Extract<SDKMessage, { type: 'rate_limit_event' }>['rate_limit_info']
+type ClaudeResultMessage = Extract<SDKMessage, { type: 'result' }>
+/** The main agent's latest context observation in the current turn: the input side of its last model response. */
+type ClaudeContextObservation = { status: 'none' } | { status: 'observed', model: string, usedTokens: number }
+/**
+ * Latest subscription usage-limit fact from `rate_limit_event`; a new event overwrites it. A rejection
+ * with a reset time (epoch seconds) stays in force until then, because the CLI throttles repeats of an
+ * unchanged rejection; one without a reset time applies only to the turn it preceded.
+ */
+type ClaudeUsageLimit
+    = | { status: 'available' }
+        | { status: 'exhausted', resetsAt?: number, rateLimitType?: ClaudeRateLimitInfo['rateLimitType'] }
 type ClaudeSubagentActor = Extract<AgentEventActor, { type: 'subagent' }>
 type TaskCreateWorkInput = Pick<TaskCreateInput, 'subject' | 'description'>
 type TaskGetWorkInput = Pick<TaskGetInput, 'taskId'>
@@ -43,6 +57,11 @@ type ClaudeUnownedTurnEventDraft = ClaudeTurnEventDraft extends infer Draft
         ? Omit<Draft, 'actor'>
         : never
     : never
+interface ClaudeActorContext { actor: AgentEventActor, turnId: string }
+type ClaudeTaskActorResolution
+    = | { status: 'resolved', context: { actor: ClaudeSubagentActor, turnId: string } }
+        | { status: 'pending' }
+        | { status: 'conflict' }
 
 const mainActor = { type: 'main', actorId: 'main' } satisfies AgentEventActor
 
@@ -99,6 +118,14 @@ export interface ClaudeEventMapperState {
     readonly usageScopeId: string
     readonly toolNameById: Map<string, string>
     readonly pendingWorkCallById: Map<string, PendingClaudeWorkCall>
+    readonly hostMcpToolCallIds: Set<string>
+    readonly mcpToolCallIdByTaskId: Map<string, string | undefined>
+    readonly endedMcpTaskIds: Set<string>
+    readonly conflictingMcpTaskIds: Set<string>
+    /** Tasks that are neither MCP tasks nor visible subagents (for example backgrounded Bash); their lifecycle has no event. */
+    readonly nonSubagentTaskIds: Set<string>
+    /** Initiating tool calls of those tasks; frames forwarded under them have no visible owner. */
+    readonly nonSubagentToolCallIds: Set<string>
     readonly startedMessageIds: Set<string>
     readonly endedMessageIds: Set<string>
     readonly streamedTextByMessageId: Map<string, string>
@@ -106,12 +133,39 @@ export interface ClaudeEventMapperState {
     readonly streamedReasoningByMessageId: Map<string, string>
     readonly contentBlockTypeByIndex: Map<number, string>
     readonly subagentByToolCallId: Map<string, ClaudeSubagentActor>
+    readonly subagentByTaskId: Map<string, ClaudeSubagentActor>
+    readonly toolOwnerById: Map<string, ClaudeActorContext>
+    readonly turnIdBySubagentId: Map<string, string>
+    /** Initiating tool call of each subagent's current run: its Agent call, then each SendMessage resume. */
+    readonly runToolCallIdBySubagentId: Map<string, string>
+    readonly pendingMessages: SDKMessage[]
+    readonly startedSubagentIds: Set<string>
+    readonly endedSubagentIds: Set<string>
     readonly actorByMessageId: Map<string, AgentEventActor>
+    readonly currentMessageIdByActorId: Map<string, string>
+    readonly contentBlockTypeByActorId: Map<string, Map<number, string>>
     readonly startedReasoningIds: Set<string>
     readonly endedReasoningIds: Set<string>
     turnStarted: boolean
     interrupt: { status: 'none' } | { status: 'requesting' | 'accepted', turnId: string }
+    contextObservation: ClaudeContextObservation
+    /** The last context snapshot reported in the current turn, so repeated frames do not re-report it. */
+    reportedContext?: AgentContextSnapshot
+    /** Context windows the CLI reported per model key in result `modelUsage`, reused for mid-turn snapshots. */
+    readonly contextWindowByModel: Map<string, number>
+    usageLimit: ClaudeUsageLimit
+    mainTurnRateLimited: boolean
+    sessionCwd?: string
+    sessionModel?: string
     sessionState?: 'running' | 'idle'
+    /** The CLI reports its own session state (CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS), so its `idle` ends the session's work. */
+    cliReportsSessionState?: true
+    /** Steering (`now`) inputs the CLI queued and has not started or dropped; they supersede the running ask. */
+    readonly queuedSteerIds: Set<string>
+    /** Submitted input identity until the main response confirms consumption. */
+    readonly promptCommandByInputId: Map<string, string>
+    /** The end of a turn whose ask a queued steer superseded; the turn continues if the steer starts. */
+    heldTurnEnd?: Extract<AgentEventDraft, { type: 'turn.ended' }>
     currentTurnId?: string
     currentCommandId?: string
     currentMessageId?: string
@@ -123,6 +177,12 @@ export function createClaudeEventMapperState(): ClaudeEventMapperState {
         usageScopeId: `claude-query:${randomUUID()}`,
         toolNameById: new Map(),
         pendingWorkCallById: new Map(),
+        hostMcpToolCallIds: new Set(),
+        mcpToolCallIdByTaskId: new Map(),
+        endedMcpTaskIds: new Set(),
+        conflictingMcpTaskIds: new Set(),
+        nonSubagentTaskIds: new Set(),
+        nonSubagentToolCallIds: new Set(),
         startedMessageIds: new Set(),
         endedMessageIds: new Set(),
         streamedTextByMessageId: new Map(),
@@ -130,72 +190,158 @@ export function createClaudeEventMapperState(): ClaudeEventMapperState {
         streamedReasoningByMessageId: new Map(),
         contentBlockTypeByIndex: new Map(),
         subagentByToolCallId: new Map(),
+        subagentByTaskId: new Map(),
+        toolOwnerById: new Map(),
+        turnIdBySubagentId: new Map(),
+        runToolCallIdBySubagentId: new Map(),
+        pendingMessages: [],
+        startedSubagentIds: new Set(),
+        endedSubagentIds: new Set(),
         actorByMessageId: new Map(),
+        currentMessageIdByActorId: new Map(),
+        contentBlockTypeByActorId: new Map(),
         startedReasoningIds: new Set(),
         endedReasoningIds: new Set(),
         turnStarted: false,
         interrupt: { status: 'none' },
+        contextObservation: { status: 'none' },
+        contextWindowByModel: new Map(),
+        queuedSteerIds: new Set(),
+        promptCommandByInputId: new Map(),
+        usageLimit: { status: 'available' },
+        mainTurnRateLimited: false,
     }
 }
 
-export function mapClaudeMessage(message: SDKMessage, state: ClaudeEventMapperState, options: { continueTurn?: boolean } = {}): AgentEventDraft[] {
+export function mapClaudeMessage(message: SDKMessage, state: ClaudeEventMapperState): AgentEventDraft[] {
+    const drafts = mapClaudeMessageWithKnownActor(message, state)
+    if (drafts === undefined) {
+        state.pendingMessages.push(message)
+        return []
+    }
+    return [...drafts, ...flushPendingMessages(state)]
+}
+
+function mapClaudeMessageWithKnownActor(message: SDKMessage, state: ClaudeEventMapperState): AgentEventDraft[] | undefined {
     const drafts: AgentEventDraft[] = []
 
+    if ('parent_tool_use_id' in message && message.parent_tool_use_id !== null && state.nonSubagentToolCallIds.has(message.parent_tool_use_id))
+        return drafts
+
+    // allowed/allowed_warning snapshots, system/api_retry, and auth_status have no provider-neutral
+    // event; Codex likewise drops its rate-limit snapshots and will-retry errors. Only a rejected
+    // limit is retained, to classify the turn failure it causes.
+    if (message.type === 'rate_limit_event') {
+        state.usageLimit = usageLimitFromRateLimitInfo(message.rate_limit_info)
+        return drafts
+    }
+
     if (message.type === 'system') {
+        if (message.subtype === 'init') {
+            state.sessionCwd = message.cwd
+            state.sessionModel = message.model
+        }
+        if (message.subtype === 'session_state_changed')
+            state.cliReportsSessionState = true
         if (message.subtype === 'session_state_changed' && message.state === 'running')
             ensureTurnStarted(drafts, state)
-        if (message.subtype === 'session_state_changed' && message.state === 'idle')
+        if (message.subtype === 'session_state_changed' && message.state === 'idle') {
+            drafts.push(...flushHeldTurnEnd(state))
             ensureSessionIdle(drafts, state)
+        }
         if (message.subtype === 'status')
             drafts.push(...mapStatusMessage(message, state))
         if (message.subtype === 'compact_boundary')
             drafts.push(...mapCompactBoundaryMessage(message, state))
-        if (message.subtype === 'task_started')
-            drafts.push(...mapTaskStartedMessage(message, state))
-        if (message.subtype === 'task_progress')
-            drafts.push(...mapTaskProgressMessage(message, state))
-        if (message.subtype === 'task_notification')
-            drafts.push(...mapTaskNotificationMessage(message, state))
+        if (message.subtype === 'task_started') {
+            const taskDrafts = mapTaskStartedMessage(message, state)
+            if (!taskDrafts)
+                return undefined
+            drafts.push(...taskDrafts)
+        }
+        if (message.subtype === 'task_progress') {
+            const taskDrafts = mapTaskProgressMessage(message, state)
+            if (!taskDrafts)
+                return undefined
+            drafts.push(...taskDrafts)
+        }
+        if (message.subtype === 'task_notification') {
+            const taskDrafts = mapTaskNotificationMessage(message, state)
+            if (!taskDrafts)
+                return undefined
+            drafts.push(...taskDrafts)
+        }
         return drafts
     }
 
     if (message.type === 'assistant') {
-        const turnId = ensureTurnStarted(drafts, state)
-        const actor = actorFromParentToolUseId(message.parent_tool_use_id, state)
+        const context = actorContextFromParentToolUseId(message.parent_tool_use_id, drafts, state)
+        if (!context)
+            return undefined
+        const { actor, turnId } = context
+        if (actor.type === 'main') {
+            correlateConsumedPrompts({ message, turnId, drafts, state })
+            observeMainAssistantMessage(message, state)
+        }
         ensureAssistantMessageStarted(drafts, state, message.message, turnId, actor)
-        drafts.push(...mapAssistantContent(message.message, state, turnId, actor, message.parent_tool_use_id === null))
+        if (actor.type === 'main')
+            reportContextSnapshot({ drafts, state, turnId })
+        drafts.push(...mapAssistantContent(message.message, state, turnId, actor, actor.type === 'main'))
         if (message.message.stop_reason !== null || shouldEndAssistantSnapshot(message.message, state, actor))
             endAssistantMessage(drafts, state, message.message, turnId, actor)
         return drafts
     }
 
     if (message.type === 'stream_event') {
-        const turnId = ensureTurnStarted(drafts, state)
-        const actor = actorFromParentToolUseId(message.parent_tool_use_id, state)
-        drafts.push(...mapStreamEvent(message.event, state, turnId, actor))
+        const context = actorContextFromParentToolUseId(message.parent_tool_use_id, drafts, state)
+        if (!context)
+            return undefined
+        if (context.actor.type === 'main')
+            correlateConsumedPrompts({ message, turnId: context.turnId, drafts, state })
+        drafts.push(...mapStreamEvent(message.event, state, context.turnId, context.actor))
         return drafts
     }
 
     if (message.type === 'user') {
-        const turnId = ensureTurnStarted(drafts, state)
-        const actor = actorFromParentToolUseId(message.parent_tool_use_id, state)
+        const context = actorContextFromParentToolUseId(message.parent_tool_use_id, drafts, state)
+        if (!context)
+            return undefined
+        const { actor, turnId } = context
         const content = message.message.content
         const messageId = message.uuid ?? `user-${turnId}`
         if (typeof content === 'string')
-            return actor ? subagentUserMessageEvents({ messageId, text: content, turnId, actor }) : drafts
-        if (actor)
+            return actor.type === 'subagent' ? subagentUserMessageEvents({ messageId, text: content, turnId, actor }) : drafts
+        if (actor.type === 'subagent')
             drafts.push(...subagentUserContentEvents({ messageId, content, turnId, actor }))
-        drafts.push(...content.flatMap(block => mapUserContentBlock(block, message, state, turnId, actor, message.parent_tool_use_id === null)))
+        const hostTrailerToolCallId = correlatedHostTrailerToolCallId({ content, message, state })
+        const structuredResultToolCallId = soleToolResultToolCallId(content)
+        drafts.push(...content.flatMap(block => mapUserContentBlock({
+            block,
+            message,
+            state,
+            turnId,
+            actor,
+            isMain: actor.type === 'main',
+            hostTrailer: block.type === 'tool_result' && block.tool_use_id === hostTrailerToolCallId ? message.tool_use_result : undefined,
+            ownsStructuredResult: block.type === 'tool_result' && block.tool_use_id === structuredResultToolCallId,
+        })))
         return drafts
     }
 
     if (message.type === 'result') {
         const turnId = ensureTurnStarted(drafts, state)
+        correlateConsumedPrompts({ message, turnId, drafts, state })
         const usage = usageFromObject(message.usage)
-        // SDK usage is per result, but modelUsage is cumulative within this query process.
-        // A resumed CLI resets modelUsage even when it retains the native session ID.
-        // Keep display counters separate; the control plane deduplicates/differences accounting.
-        if (usage) {
+        // Claude Agent SDK result usage is per completed ask/turn for the stream-json path we use,
+        // not a monotonic counter across the long-lived query. Emit it directly so summing
+        // normalized usage events gives the run total; do not diff against prior results.
+        // modelUsage is cumulative within this query process and resets when a resumed CLI starts;
+        // accounting keeps that distinction so the control plane can deduplicate observations.
+        // Accounting needs the result's own identity; a result without one still reports usage.
+        if (usage && !message.uuid) {
+            drafts.push({ type: 'usage', turnId, actor: mainActor, payload: { usage } })
+        }
+        else if (usage) {
             drafts.push({ type: 'usage', turnId, actor: mainActor, payload: { usage, accounting: {
                 observationId: message.uuid,
                 mode: Object.keys(message.modelUsage ?? {}).length ? 'cumulative' : 'increment',
@@ -210,36 +356,68 @@ export function mapClaudeMessage(message: SDKMessage, state: ClaudeEventMapperSt
                 }])),
             } } })
         }
-        // A native steer may finish one query segment while retaining the logical turn.
-        // Usage belongs to this segment and must still be emitted exactly once. The segment
-        // may have been aborted mid-generation (error_during_execution): close whatever it
-        // streamed so the steer's user message follows a closed assistant step.
-        if (options.continueTurn) {
-            endOpenReasoning(drafts, state, turnId)
-            endOpenAssistantMessage(drafts, state, turnId)
-            return drafts
-        }
+        reportContextSnapshot({ drafts, state, turnId, result: message })
         endOpenReasoning(drafts, state, turnId)
         const interruptAccepted = state.interrupt.status === 'accepted' && state.interrupt.turnId === turnId
-        drafts.push({ type: 'turn.ended', turnId, actor: mainActor, payload: turnEndedPayload(message, interruptAccepted) })
-        ensureSessionIdle(drafts, state)
+        const usageLimit = state.mainTurnRateLimited ? usageLimitInForce(state.usageLimit, Date.now()) : undefined
+        const ended: Extract<AgentEventDraft, { type: 'turn.ended' }> = { type: 'turn.ended', turnId, actor: mainActor, payload: turnEndedPayload({ message, interruptAccepted, usageLimit }) }
         state.pendingWorkCallById.clear()
-        state.turnStarted = false
-        state.interrupt = { status: 'none' }
-        state.currentTurnId = undefined
-        state.currentCommandId = undefined
+        state.contextObservation = { status: 'none' }
+        const heldBySteer = !interruptAccepted && state.queuedSteerIds.size > 0
+        // A superseded ask may end mid-response: close the streamed message before the steer's
+        // input can enter the continued turn.
+        if (heldBySteer)
+            endOpenAssistantMessage(drafts, state, turnId)
         state.currentMessageId = undefined
+        state.contentBlockTypeByIndex.clear()
         state.currentCompactionId = undefined
+        // Claude Code steers by superseding: a `now` input cancels the running ask, which ends with
+        // this result (`error_during_execution` before any model output), and the CLI then starts the
+        // steer on the same transcript. The turn stays open until the steer starts (it continues) or is
+        // dropped, or the CLI goes idle (the held end is final). An accepted interrupt always ends it.
+        if (heldBySteer) {
+            state.heldTurnEnd = ended
+            return drafts
+        }
+        drafts.push(ended)
+        endTurn(drafts, state)
         return drafts
     }
 
     return drafts
 }
 
+function correlateConsumedPrompts({ message, turnId, drafts, state }: {
+    message: Extract<SDKMessage, { type: 'assistant' | 'stream_event' | 'result' }>
+    turnId: string
+    drafts: AgentEventDraft[]
+    state: ClaudeEventMapperState
+}): void {
+    // Pair with the turn assigned to this very frame, after ensureTurnStarted and before result
+    // clears it. Lifecycle receipts and the turn active at submission do not prove consumption.
+    // SDK 0.3.257 declares only the singular field; 0.3.280 adds merged-input UUIDs.
+    const inputIds = 'user_message_uuids' in message && Array.isArray(message.user_message_uuids)
+        ? message.user_message_uuids.filter((id): id is string => typeof id === 'string')
+        : message.user_message_uuid ? [message.user_message_uuid] : []
+    for (const inputId of inputIds) {
+        // Main-response UUIDs prove consumption even if the started receipt was omitted. This
+        // also applies to supervisor inputs, which intentionally have no human-prompt correlation.
+        if (state.queuedSteerIds.delete(inputId))
+            state.heldTurnEnd = undefined
+        const commandId = state.promptCommandByInputId.get(inputId)
+        if (!commandId)
+            continue
+        drafts.push({ type: 'prompt.turn-correlated', payload: { commandId, turnId } })
+        state.promptCommandByInputId.delete(inputId)
+    }
+}
+
 function mapStatusMessage(message: ClaudeStatusMessage, state: ClaudeEventMapperState): AgentEventDraft[] {
     const drafts: AgentEventDraft[] = []
     if (message.status === 'compacting') {
         const turnId = ensureTurnStarted(drafts, state)
+        state.contextObservation = { status: 'none' }
+        state.reportedContext = undefined
         if (state.currentCompactionId)
             return drafts
         state.currentCompactionId = message.uuid
@@ -258,7 +436,7 @@ function mapStatusMessage(message: ClaudeStatusMessage, state: ClaudeEventMapper
                 compactionId,
                 trigger: 'unknown',
                 status: 'failed',
-                error: { message: message.compact_error ?? 'Claude compaction failed.' },
+                error: compactionError(message),
             },
         })
         state.currentCompactionId = undefined
@@ -267,13 +445,44 @@ function mapStatusMessage(message: ClaudeStatusMessage, state: ClaudeEventMapper
     return drafts
 }
 
-function mapTaskStartedMessage(message: ClaudeTaskStartedMessage, state: ClaudeEventMapperState): AgentEventDraft[] {
-    const drafts: AgentEventDraft[] = []
-    const turnId = ensureTurnStarted(drafts, state)
-    const actor = subagentActorFromTask({ subagentId: message.task_id, parentToolCallId: message.tool_use_id, name: message.subagent_type })
-    if (message.tool_use_id)
-        state.subagentByToolCallId.set(message.tool_use_id, actor)
-    drafts.push({
+function isMcpTaskMessage(message: { task_id: string, tool_use_id?: string }, state: ClaudeEventMapperState): boolean {
+    if (state.mcpToolCallIdByTaskId.has(message.task_id))
+        return true
+    const name = message.tool_use_id ? state.toolNameById.get(message.tool_use_id) : undefined
+    return name !== undefined && isHostMcpToolName(name)
+}
+
+/**
+ * Only an Agent-tool child (`local_agent`) is a subagent; the CLI also reports backgrounded Bash,
+ * workflows, monitors, and other tasks through the same lifecycle. The pinned CLI always sets the
+ * task type; an untyped task keeps the subagent mapping its ancestry evidence supports. The SDK
+ * marks housekeeping tasks `skip_transcript` for hosts to hide.
+ */
+function isVisibleSubagentTask(message: ClaudeTaskStartedMessage): boolean {
+    return (message.task_type === undefined || message.task_type === 'local_agent') && message.skip_transcript !== true
+}
+
+/**
+ * SendMessage resumes a finished subagent as a new run: the CLI repeats its task_id with the
+ * SendMessage call as tool_use_id. The run keeps the subagent's identity and turn, so it reopens the
+ * same subagent. Returns null when the message is not a resume of a known subagent.
+ */
+function mapResumedSubagentRun(message: ClaudeTaskStartedMessage, state: ClaudeEventMapperState): AgentEventDraft[] | undefined | null {
+    const actor = state.subagentByTaskId.get(message.task_id)
+    const toolCallId = message.tool_use_id
+    if (!actor || !toolCallId || toolCallId === actor.parentToolCallId || state.subagentByToolCallId.has(toolCallId))
+        return null
+    const owner = state.toolOwnerById.get(toolCallId)
+    if (!owner)
+        return undefined
+    const turnId = state.turnIdBySubagentId.get(message.task_id)
+    if (owner.actor.actorId !== actor.parentActorId || !turnId)
+        return []
+
+    state.subagentByToolCallId.set(toolCallId, actor)
+    state.runToolCallIdBySubagentId.set(message.task_id, toolCallId)
+    state.endedSubagentIds.delete(message.task_id)
+    return [{
         type: 'subagent.started',
         turnId,
         actor,
@@ -281,51 +490,134 @@ function mapTaskStartedMessage(message: ClaudeTaskStartedMessage, state: ClaudeE
             ...subagentPayloadRef(actor),
             description: message.description,
         }),
-    })
-    return drafts
+    }]
 }
 
-function mapTaskProgressMessage(message: ClaudeTaskProgressMessage, state: ClaudeEventMapperState): AgentEventDraft[] {
-    const drafts: AgentEventDraft[] = []
-    const turnId = ensureTurnStarted(drafts, state)
-    const actor = subagentActorForTaskMessage({ subagentId: message.task_id, parentToolCallId: message.tool_use_id, name: message.subagent_type }, state)
-    drafts.push({
-        type: 'subagent.progress',
+/** A resumed subagent must not take progress or a terminal from a run that SendMessage superseded. */
+function isEarlierSubagentRun(message: { task_id: string, tool_use_id?: string }, state: ClaudeEventMapperState): boolean {
+    const runToolCallId = state.runToolCallIdBySubagentId.get(message.task_id)
+    return message.tool_use_id !== undefined && runToolCallId !== undefined && message.tool_use_id !== runToolCallId
+}
+
+function mapTaskStartedMessage(message: ClaudeTaskStartedMessage, state: ClaudeEventMapperState): AgentEventDraft[] | undefined {
+    if (message.task_type === 'mcp_task' || isMcpTaskMessage(message, state)) {
+        const previous = state.mcpToolCallIdByTaskId.get(message.task_id)
+        if (previous && message.tool_use_id && previous !== message.tool_use_id)
+            state.conflictingMcpTaskIds.add(message.task_id)
+        else
+            state.mcpToolCallIdByTaskId.set(message.task_id, previous ?? message.tool_use_id)
+        return []
+    }
+    if (!isVisibleSubagentTask(message)) {
+        state.nonSubagentTaskIds.add(message.task_id)
+        if (message.tool_use_id)
+            state.nonSubagentToolCallIds.add(message.tool_use_id)
+        return []
+    }
+    const resumed = mapResumedSubagentRun(message, state)
+    if (resumed !== null)
+        return resumed
+    const resolution = subagentActorForTaskMessage({ subagentId: message.task_id, parentToolCallId: message.tool_use_id, name: message.subagent_type }, state)
+    if (resolution.status === 'pending')
+        return undefined
+    if (resolution.status === 'conflict' || state.startedSubagentIds.has(message.task_id))
+        return []
+
+    state.startedSubagentIds.add(message.task_id)
+    const { actor, turnId } = resolution.context
+    return [{
+        type: 'subagent.started',
         turnId,
         actor,
         payload: removeUndefined({
             ...subagentPayloadRef(actor),
-            summary: optionalNonEmpty(message.summary),
-            lastToolName: optionalNonEmpty(message.last_tool_name),
-            usage: usageFromTaskUsage(message.usage),
+            description: message.description,
         }),
-    })
-    return drafts
+    }]
 }
 
-function mapTaskNotificationMessage(message: ClaudeTaskNotificationMessage, state: ClaudeEventMapperState): AgentEventDraft[] {
-    const drafts: AgentEventDraft[] = []
-    const turnId = ensureTurnStarted(drafts, state)
-    const actor = subagentActorForTaskMessage({ subagentId: message.task_id, parentToolCallId: message.tool_use_id }, state)
-    drafts.push({
-        type: 'subagent.ended',
+function mapTaskProgressMessage(message: ClaudeTaskProgressMessage, state: ClaudeEventMapperState): AgentEventDraft[] | undefined {
+    if (isMcpTaskMessage(message, state)) {
+        if (!state.mcpToolCallIdByTaskId.has(message.task_id))
+            state.mcpToolCallIdByTaskId.set(message.task_id, message.tool_use_id)
+        return []
+    }
+    if (state.nonSubagentTaskIds.has(message.task_id))
+        return []
+    const resolution = subagentActorForTaskMessage({ subagentId: message.task_id, parentToolCallId: message.tool_use_id, name: message.subagent_type }, state)
+    if (resolution.status === 'pending')
+        return undefined
+    if (resolution.status === 'conflict' || isEarlierSubagentRun(message, state))
+        return []
+
+    const { actor, turnId } = resolution.context
+    return [{
+        type: 'subagent.progress',
         turnId,
         actor,
         payload: removeUndefined({
             ...subagentPayloadRef(actor),
-            status: taskNotificationStatus(message.status),
             summary: optionalNonEmpty(message.summary),
-            usage: message.usage ? usageFromTaskUsage(message.usage) : undefined,
-            error: message.status === 'failed' ? { message: optionalNonEmpty(message.summary) ?? `Subagent ${message.task_id} failed.` } : undefined,
+            lastToolName: optionalNonEmpty(message.last_tool_name),
+            usage: usageFromTaskUsage(message.usage),
         }),
-    })
-    return drafts
+    }]
+}
+
+function mapTaskNotificationMessage(message: ClaudeTaskNotificationMessage, state: ClaudeEventMapperState): AgentEventDraft[] | undefined {
+    if (isMcpTaskMessage(message, state) || message.resource_links !== undefined) {
+        const rememberedToolCallId = state.mcpToolCallIdByTaskId.get(message.task_id)
+        if (rememberedToolCallId && message.tool_use_id && rememberedToolCallId !== message.tool_use_id)
+            state.conflictingMcpTaskIds.add(message.task_id)
+        if (state.endedMcpTaskIds.has(message.task_id) || state.conflictingMcpTaskIds.has(message.task_id))
+            return []
+        const toolCallId = message.tool_use_id ?? rememberedToolCallId
+        const owner = toolCallId ? state.toolOwnerById.get(toolCallId) : undefined
+        if (!toolCallId || !owner)
+            return undefined
+        state.endedMcpTaskIds.add(message.task_id)
+        const content: AgentToolContent[] = [{ type: 'text', text: message.summary }]
+        content.push(...(message.resource_links ?? []).map(link => resourceLinkContent(jsonValueSchema.parse(link))))
+        if (message.output_file !== '')
+            content.push(jsonToolContent({ outputFile: message.output_file }))
+        return [{
+            type: 'tool.output.updated',
+            ...owner,
+            payload: { toolCallId, output: { success: message.status === 'completed', content } },
+        }]
+    }
+    if (state.nonSubagentTaskIds.has(message.task_id))
+        return []
+    const resolution = subagentActorForTaskMessage({ subagentId: message.task_id, parentToolCallId: message.tool_use_id }, state)
+    if (resolution.status === 'pending')
+        return undefined
+    if (resolution.status === 'conflict' || isEarlierSubagentRun(message, state) || state.endedSubagentIds.has(message.task_id))
+        return []
+
+    state.endedSubagentIds.add(message.task_id)
+    const { actor, turnId } = resolution.context
+    return [
+        {
+            type: 'subagent.ended',
+            turnId,
+            actor,
+            payload: removeUndefined({
+                ...subagentPayloadRef(actor),
+                status: taskNotificationStatus(message.status),
+                summary: optionalNonEmpty(message.summary),
+                usage: message.usage ? usageFromTaskUsage(message.usage) : undefined,
+                error: message.status === 'failed' ? { message: optionalNonEmpty(message.summary) ?? `Subagent ${message.task_id} failed.` } : undefined,
+            }),
+        },
+    ]
 }
 
 function mapCompactBoundaryMessage(message: ClaudeCompactBoundaryMessage, state: ClaudeEventMapperState): AgentEventDraft[] {
     const drafts: AgentEventDraft[] = []
     const turnId = ensureTurnStarted(drafts, state)
     const compactionId = state.currentCompactionId ?? message.uuid
+    state.contextObservation = { status: 'none' }
+    state.reportedContext = undefined
     drafts.push({
         type: 'context.compaction.completed',
         turnId,
@@ -343,7 +635,7 @@ function mapCompactBoundaryMessage(message: ClaudeCompactBoundaryMessage, state:
     return drafts
 }
 
-function mapAssistantContent(message: BetaMessage, state: ClaudeEventMapperState, turnId: string, actor: AgentEventActor | undefined, isMain: boolean): AgentEventDraft[] {
+function mapAssistantContent(message: BetaMessage, state: ClaudeEventMapperState, turnId: string, actor: AgentEventActor, isMain: boolean): AgentEventDraft[] {
     const drafts: AgentEventDraft[] = []
     const streamedText = state.streamedTextByMessageId.has(message.id)
     const streamedReasoning = state.streamedReasoningMessageIds.has(message.id)
@@ -360,6 +652,12 @@ function mapAssistantContent(message: BetaMessage, state: ClaudeEventMapperState
         if (block.type === 'tool_use') {
             const toolName = normalizeToolName(block.name)
             state.toolNameById.set(block.id, toolName)
+            if (isHostMcpToolName(block.name))
+                state.hostMcpToolCallIds.add(block.id)
+            // SDK task_id identifies the child, while task_started.tool_use_id identifies this
+            // initiating call; the actor that emitted the tool_use is the only ancestry evidence.
+            if (!state.toolOwnerById.has(block.id))
+                state.toolOwnerById.set(block.id, { actor, turnId })
             if (isMain) {
                 const pendingWorkCall = pendingClaudeWorkCall(block.name, block.input)
                 if (pendingWorkCall)
@@ -371,27 +669,53 @@ function mapAssistantContent(message: BetaMessage, state: ClaudeEventMapperState
     return drafts
 }
 
-function mapUserContentBlock(block: UserContentBlock, message: ClaudeUserMessage, state: ClaudeEventMapperState, turnId: string, actor: AgentEventActor | undefined, isMain: boolean): AgentEventDraft[] {
+function mapUserContentBlock(input: {
+    block: UserContentBlock
+    message: ClaudeUserMessage
+    state: ClaudeEventMapperState
+    turnId: string
+    actor: AgentEventActor
+    isMain: boolean
+    hostTrailer?: unknown
+    ownsStructuredResult: boolean
+}): AgentEventDraft[] {
+    const { block, message, state, turnId, actor, isMain, hostTrailer, ownsStructuredResult } = input
     if (block.type !== 'tool_result')
         return []
     const toolCallId = block.tool_use_id
     const pendingWorkCall = state.pendingWorkCallById.get(toolCallId)
     if (pendingWorkCall)
         state.pendingWorkCallById.delete(toolCallId)
-
-    const text = textFromToolResultContent(block.content)
-    const output = { success: block.is_error !== true, content: text ? [{ type: 'text' as const, text }] : [] }
+    state.hostMcpToolCallIds.delete(toolCallId)
+
+    const fileChangeText = ownsStructuredResult && block.is_error !== true
+        ? claudeFileChangeText({ toolName: state.toolNameById.get(toolCallId), toolUseResult: message.tool_use_result, cwd: state.sessionCwd })
+        : undefined
+    const mapped = fileChangeText === undefined
+        ? mappedModelToolResultContent({ content: block.content, isError: block.is_error === true })
+        : { content: [{ type: 'text' as const, text: fileChangeText }], text: fileChangeText }
+    const content = hostTrailer === undefined ? mapped.content : mappedHostMcpContent({ trailer: hostTrailer, modelBlocks: mapped.content })
+    const structuredContent = ownJsonSlot(hostTrailer, 'structuredContent')
+    const reportedError = ownJsonSlot(hostTrailer, 'isError')
+    const output = removeUndefined({
+        success: block.is_error !== true,
+        content,
+        structuredContent,
+        reportedSuccess: typeof reportedError === 'boolean' ? !reportedError : undefined,
+    })
     const drafts: AgentEventDraft[] = []
-    if (text)
-        drafts.push(withActor({ type: 'tool.output.delta', turnId, payload: { toolCallId, delta: text } }, actor))
+    if (mapped.text !== undefined)
+        drafts.push(withActor({ type: 'tool.output.delta', turnId, payload: { toolCallId, delta: mapped.text } }, actor))
     drafts.push(withActor({
         type: 'tool.call.completed',
         turnId,
         payload: removeUndefined({
             toolCallId,
+            toolName: state.toolNameById.get(toolCallId),
             status: block.is_error === true ? 'failed' : 'completed',
             output,
-            error: block.is_error === true ? { message: text || `Tool ${state.toolNameById.get(toolCallId) ?? toolCallId} failed.` } : undefined,
+            // The failure detail already rides in output; like Codex, the error is a short summary.
+            error: block.is_error === true ? { message: `Tool ${state.toolNameById.get(toolCallId) ?? toolCallId} failed.` } : undefined,
         }),
     }, actor))
 
@@ -468,20 +792,19 @@ function parseClaudeTaskResult<Output>({ value, toolName, schema }: { value: unk
     })
 }
 
-function mapStreamEvent(event: BetaRawMessageStreamEvent, state: ClaudeEventMapperState, turnId: string, actor: AgentEventActor | undefined): AgentEventDraft[] {
+function mapStreamEvent(event: BetaRawMessageStreamEvent, state: ClaudeEventMapperState, turnId: string, actor: AgentEventActor): AgentEventDraft[] {
     const drafts: AgentEventDraft[] = []
     if (event.type === 'message_start') {
-        state.currentMessageId = event.message.id
-        if (actor)
-            state.actorByMessageId.set(event.message.id, actor)
+        setCurrentMessageId(state, actor, event.message.id)
+        state.actorByMessageId.set(event.message.id, actor)
         ensureAssistantMessageStarted(drafts, state, event.message, turnId, actor)
         return drafts
     }
 
     if (event.type === 'content_block_start') {
-        const messageId = currentMessageId(state)
-        const messageActor = actor ?? state.actorByMessageId.get(messageId)
-        state.contentBlockTypeByIndex.set(event.index, event.content_block.type)
+        const messageId = currentMessageId(state, actor)
+        const messageActor = state.actorByMessageId.get(messageId) ?? actor
+        contentBlockTypes(state, actor).set(event.index, event.content_block.type)
         if (event.content_block.type === 'thinking') {
             state.streamedReasoningMessageIds.add(messageId)
             ensureReasoningStarted(drafts, state, turnId, messageId, messageActor)
@@ -490,30 +813,30 @@ function mapStreamEvent(event: BetaRawMessageStreamEvent, state: ClaudeEventMapp
     }
 
     if (event.type === 'content_block_stop') {
-        const messageId = currentMessageId(state)
-        const messageActor = actor ?? state.actorByMessageId.get(messageId)
-        const blockType = state.contentBlockTypeByIndex.get(event.index)
+        const messageId = currentMessageId(state, actor)
+        const messageActor = state.actorByMessageId.get(messageId) ?? actor
+        const blockTypes = contentBlockTypes(state, actor)
+        const blockType = blockTypes.get(event.index)
         if (blockType === 'thinking')
             endReasoning(drafts, state, turnId, messageId, state.streamedReasoningByMessageId.get(messageId), messageActor)
-        state.contentBlockTypeByIndex.delete(event.index)
+        blockTypes.delete(event.index)
         return drafts
     }
 
     if (event.type === 'message_stop') {
-        const messageId = currentMessageId(state)
-        const messageActor = actor ?? state.actorByMessageId.get(messageId)
+        const messageId = currentMessageId(state, actor)
+        const messageActor = state.actorByMessageId.get(messageId) ?? actor
         endAssistantMessageById(drafts, state, turnId, messageId, state.streamedTextByMessageId.get(messageId), messageActor)
         state.actorByMessageId.delete(messageId)
-        state.currentMessageId = undefined
-        state.contentBlockTypeByIndex.clear()
+        clearCurrentMessage(state, actor)
         return drafts
     }
 
     if (event.type !== 'content_block_delta')
         return drafts
 
-    const messageId = currentMessageId(state)
-    const messageActor = actor ?? state.actorByMessageId.get(messageId)
+    const messageId = currentMessageId(state, actor)
+    const messageActor = state.actorByMessageId.get(messageId) ?? actor
     const delta = event.delta
     if (delta.type === 'thinking_delta') {
         state.streamedReasoningMessageIds.add(messageId)
@@ -530,18 +853,64 @@ function mapStreamEvent(event: BetaRawMessageStreamEvent, state: ClaudeEventMapp
 }
 
 function ensureTurnStarted(drafts: AgentEventDraft[], state: ClaudeEventMapperState): string {
-    if (state.turnStarted && state.currentTurnId)
-        return state.currentTurnId
-    state.turnStarted = true
-    state.interrupt = { status: 'none' }
-    state.currentTurnId = createRuntimeTurnId()
-    state.currentMessageId = undefined
-    state.contentBlockTypeByIndex.clear()
-    drafts.push({ type: 'turn.started', turnId: state.currentTurnId, actor: mainActor, payload: removeUndefined({ commandId: state.currentCommandId }) })
+    if (!state.turnStarted || !state.currentTurnId) {
+        state.turnStarted = true
+        state.interrupt = { status: 'none' }
+        state.currentTurnId = createRuntimeTurnId()
+        state.currentMessageId = undefined
+        state.contentBlockTypeByIndex.clear()
+        drafts.push({ type: 'turn.started', turnId: state.currentTurnId, actor: mainActor, payload: removeUndefined({ commandId: state.currentCommandId }) })
+    }
     ensureSessionRunning(drafts, state)
     return state.currentTurnId
 }
 
+// Turn-scoped state after the main turn's `turn.ended`. With CLI state events the CLI's own `idle`
+// ends the session's work; without them the turn end is the only turn-over signal.
+function endTurn(drafts: AgentEventDraft[], state: ClaudeEventMapperState): void {
+    if (!state.cliReportsSessionState)
+        ensureSessionIdle(drafts, state)
+    state.reportedContext = undefined
+    state.mainTurnRateLimited = false
+    state.usageLimit = usageLimitAfterTurn(state.usageLimit)
+    state.turnStarted = false
+    state.interrupt = { status: 'none' }
+    state.currentTurnId = undefined
+    state.currentCommandId = undefined
+}
+
+/** Emits a superseded turn's held end as final: its steer will not continue it. */
+export function flushHeldTurnEnd(state: ClaudeEventMapperState): AgentEventDraft[] {
+    const held = state.heldTurnEnd
+    if (!held)
+        return []
+    state.heldTurnEnd = undefined
+    const drafts: AgentEventDraft[] = [held]
+    endTurn(drafts, state)
+    return drafts
+}
+
+/**
+ * Applies the CLI's `command_lifecycle` receipt for a steering input. `queued` marks a pending
+ * supersession; `started` continues the held turn (or starts one, so an interrupt has a target);
+ * any other state drops the steer, and the held end is final once no steer can continue it.
+ */
+export function mapSteerLifecycle(input: { steerId: string, state: 'queued' | 'started' | 'completed' | 'cancelled' | 'discarded' | 'refused' }, state: ClaudeEventMapperState): AgentEventDraft[] {
+    if (input.state === 'queued') {
+        state.queuedSteerIds.add(input.steerId)
+        return []
+    }
+    if (!state.queuedSteerIds.delete(input.steerId) && input.state !== 'started')
+        return []
+    if (input.state === 'started') {
+        state.heldTurnEnd = undefined
+        const drafts: AgentEventDraft[] = []
+        ensureTurnStarted(drafts, state)
+        return drafts
+    }
+    return state.queuedSteerIds.size === 0 ? flushHeldTurnEnd(state) : []
+}
+
 function ensureSessionRunning(drafts: AgentEventDraft[], state: ClaudeEventMapperState): void {
     if (state.sessionState === 'running')
         return
@@ -556,22 +925,49 @@ function ensureSessionIdle(drafts: AgentEventDraft[], state: ClaudeEventMapperSt
     drafts.push({ type: 'session.state.changed', payload: { state: 'idle' } })
 }
 
-function ensureAssistantMessageStarted(drafts: AgentEventDraft[], state: ClaudeEventMapperState, message: BetaMessage, turnId: string, actor: AgentEventActor | undefined): void {
-    state.currentMessageId = message.id
-    if (actor)
-        state.actorByMessageId.set(message.id, actor)
+function ensureAssistantMessageStarted(drafts: AgentEventDraft[], state: ClaudeEventMapperState, message: BetaMessage, turnId: string, actor: AgentEventActor): void {
+    setCurrentMessageId(state, actor, message.id)
+    state.actorByMessageId.set(message.id, actor)
     if (state.startedMessageIds.has(message.id))
         return
     state.startedMessageIds.add(message.id)
     drafts.push(withActor({ type: 'message.started', turnId, payload: { messageId: message.id, role: 'assistant' } }, actor))
 }
 
-function currentMessageId(state: ClaudeEventMapperState): string {
-    if (state.currentMessageId)
-        return state.currentMessageId
+function setCurrentMessageId(state: ClaudeEventMapperState, actor: AgentEventActor, messageId: string): void {
+    if (actor.type === 'main')
+        state.currentMessageId = messageId
+    else state.currentMessageIdByActorId.set(actor.actorId, messageId)
+}
+
+function currentMessageId(state: ClaudeEventMapperState, actor: AgentEventActor): string {
+    const messageId = actor.type === 'main' ? state.currentMessageId : state.currentMessageIdByActorId.get(actor.actorId)
+    if (messageId)
+        return messageId
     throw new AgentProviderProtocolError({ message: 'Claude stream emitted content_block_delta before message_start.' })
 }
 
+function contentBlockTypes(state: ClaudeEventMapperState, actor: AgentEventActor): Map<number, string> {
+    if (actor.type === 'main')
+        return state.contentBlockTypeByIndex
+    const existing = state.contentBlockTypeByActorId.get(actor.actorId)
+    if (existing)
+        return existing
+    const created = new Map<number, string>()
+    state.contentBlockTypeByActorId.set(actor.actorId, created)
+    return created
+}
+
+function clearCurrentMessage(state: ClaudeEventMapperState, actor: AgentEventActor): void {
+    if (actor.type === 'main') {
+        state.currentMessageId = undefined
+        state.contentBlockTypeByIndex.clear()
+        return
+    }
+    state.currentMessageIdByActorId.delete(actor.actorId)
+    state.contentBlockTypeByActorId.delete(actor.actorId)
+}
+
 function endAssistantMessage(drafts: AgentEventDraft[], state: ClaudeEventMapperState, message: BetaMessage, turnId: string, actor: AgentEventActor | undefined): void {
     if (state.endedMessageIds.has(message.id))
         return
@@ -605,7 +1001,9 @@ function endReasoning(drafts: AgentEventDraft[], state: ClaudeEventMapperState,
 
 function endOpenReasoning(drafts: AgentEventDraft[], state: ClaudeEventMapperState, turnId: string): void {
     for (const reasoningId of state.startedReasoningIds) {
-        if (!state.endedReasoningIds.has(reasoningId)) {
+        const messageId = reasoningId.slice('reasoning-'.length)
+        const actor = state.actorByMessageId.get(messageId)
+        if (actor?.type === 'main' && !state.endedReasoningIds.has(reasoningId)) {
             state.endedReasoningIds.add(reasoningId)
             drafts.push({ type: 'reasoning.ended', turnId, actor: mainActor, payload: { reasoningId } })
         }
@@ -626,7 +1024,11 @@ function reasoningIdForMessage(messageId: string): string {
     return `reasoning-${messageId}`
 }
 
-function turnEndedPayload(message: Extract<SDKMessage, { type: 'result' }>, interruptAccepted: boolean): Extract<AgentEventDraft, { type: 'turn.ended' }>['payload'] {
+function turnEndedPayload({ message, interruptAccepted, usageLimit }: {
+    message: ClaudeResultMessage
+    interruptAccepted: boolean
+    usageLimit: Extract<ClaudeUsageLimit, { status: 'exhausted' }> | undefined
+}): Extract<AgentEventDraft, { type: 'turn.ended' }>['payload'] {
     if (interruptAccepted && message.subtype === 'error_during_execution') {
         return removeUndefined({
             status: 'interrupted' as const,
@@ -647,45 +1049,227 @@ function turnEndedPayload(message: Extract<SDKMessage, { type: 'result' }>, inte
         status: 'failed' as const,
         reason: message.stop_reason ?? message.subtype,
         duration: message.duration_ms,
-        error: resultError(message),
+        error: usageLimit ? usageLimitError({ error: resultError(message), usageLimit }) : resultError(message),
     })
 }
 
-function resultError(message: Extract<SDKMessage, { type: 'result' }>): AgentError {
-    const errors = 'errors' in message && Array.isArray(message.errors) ? message.errors : []
+// Codex reports a plan usage limit as codexErrorInfo `usageLimitExceeded`; reuse that code so
+// consumers classify both providers alike. The reset time rides on `cause` because AgentError
+// has no structured slot for it.
+function usageLimitError({ error, usageLimit }: { error: AgentError, usageLimit: Extract<ClaudeUsageLimit, { status: 'exhausted' }> }): AgentError {
+    const resetsAt = usageLimit.resetsAt === undefined ? undefined : isoFromEpochSeconds(usageLimit.resetsAt)
+    return removeUndefined({
+        message: error.message,
+        code: 'usageLimitExceeded',
+        cause: resetsAt ? removeUndefined({ message: `Claude usage limit resets at ${resetsAt}.`, code: usageLimit.rateLimitType }) : undefined,
+    })
+}
+
+function usageLimitFromRateLimitInfo(info: ClaudeRateLimitInfo): ClaudeUsageLimit {
+    if (info.status !== 'rejected')
+        return { status: 'available' }
+    const resetsAt = info.resetsAt !== undefined && Number.isFinite(info.resetsAt) && info.resetsAt > 0 ? info.resetsAt : undefined
+    return removeUndefined({ status: 'exhausted' as const, resetsAt, rateLimitType: info.rateLimitType })
+}
+
+// Mirrors the CLI's own expiry check (`resetsAt * 1000 <= Date.now()` on CLI 2.1.280).
+function usageLimitInForce(limit: ClaudeUsageLimit, nowMs: number): Extract<ClaudeUsageLimit, { status: 'exhausted' }> | undefined {
+    if (limit.status !== 'exhausted')
+        return undefined
+    return limit.resetsAt === undefined || nowMs < limit.resetsAt * 1000 ? limit : undefined
+}
+
+function usageLimitAfterTurn(limit: ClaudeUsageLimit): ClaudeUsageLimit {
+    return limit.status === 'exhausted' && limit.resetsAt !== undefined ? limit : { status: 'available' }
+}
+
+function isoFromEpochSeconds(seconds: number): string | undefined {
+    const date = new Date(seconds * 1000)
+    return Number.isFinite(seconds) && seconds > 0 && Number.isFinite(date.getTime()) ? date.toISOString() : undefined
+}
+
+function observeMainAssistantMessage(message: Extract<SDKMessage, { type: 'assistant' }>, state: ClaudeEventMapperState): void {
+    if (message.error === 'rate_limit')
+        state.mainTurnRateLimited = true
+    // Claude Code's own context report counts the last response's input side (verified against
+    // getContextUsage on CLI 2.1.280); output is partial on streamed frames and previous thinking
+    // is dropped from later requests. A zero input side is a synthetic frame, not an observation.
+    const { usage } = message.message
+    const usedTokens = usage.input_tokens + (usage.cache_creation_input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0)
+    if (usedTokens > 0 && Number.isSafeInteger(usedTokens))
+        state.contextObservation = { status: 'observed', model: message.message.model, usedTokens }
+}
+
+// Codex reports context on every token-usage update; Claude's equivalent is each main response,
+// so report whenever the snapshot changes and again at turn end once the result names the window.
+function reportContextSnapshot({ drafts, state, turnId, result }: {
+    drafts: AgentEventDraft[]
+    state: ClaudeEventMapperState
+    turnId: string
+    result?: ClaudeResultMessage
+}): void {
+    if (state.contextObservation.status !== 'observed' || state.currentCompactionId !== undefined)
+        return
+    if (result)
+        rememberContextWindows(result, state)
+    const snapshot = contextSnapshot({ observation: state.contextObservation, state })
+    if (state.reportedContext !== undefined && contextSnapshotsEqual(snapshot, state.reportedContext))
+        return
+    state.reportedContext = snapshot
+    drafts.push({ type: 'context.updated', turnId, actor: mainActor, payload: { snapshot } })
+}
+
+function rememberContextWindows(result: ClaudeResultMessage, state: ClaudeEventMapperState): void {
+    for (const [model, usage] of Object.entries(result.modelUsage)) {
+        if (Number.isSafeInteger(usage.contextWindow) && usage.contextWindow > 0)
+            state.contextWindowByModel.set(model, usage.contextWindow)
+    }
+}
+
+function contextSnapshot({ observation, state }: {
+    observation: Extract<ClaudeContextObservation, { status: 'observed' }>
+    state: ClaudeEventMapperState
+}): AgentContextSnapshot {
+    // modelUsage is keyed by the requested model string, which is the init model for an explicit id
+    // and the resolved id (also the assistant model) for an alias.
+    const capacityTokens = state.contextWindowByModel.get(observation.model)
+        ?? (state.sessionModel === undefined ? undefined : state.contextWindowByModel.get(state.sessionModel))
+    if (capacityTokens === undefined)
+        return { status: 'observed', usedTokens: observation.usedTokens, window: { status: 'unknown' } }
+    // Claude Code reports context against the raw window without a reserved baseline.
+    const remainingPercent = Math.round(Math.min(Math.max(100 * (capacityTokens - observation.usedTokens) / capacityTokens, 0), 100))
+    return { status: 'observed', usedTokens: observation.usedTokens, window: { status: 'known', capacityTokens, remainingPercent } }
+}
+
+function contextSnapshotsEqual(left: AgentContextSnapshot, right: AgentContextSnapshot): boolean {
+    return JSON.stringify(left) === JSON.stringify(right)
+}
+
+export function compactionError(message: ClaudeStatusMessage): AgentError {
+    return { message: message.compact_error || 'Claude compaction failed.' }
+}
+
+export function resultError(message: Extract<SDKMessage, { type: 'result' }>): AgentError {
+    // SDK success/is_error carries API failure text in result rather than the errors array.
+    const detail = message.subtype === 'success'
+        ? message.result
+        : message.errors.length > 0 ? message.errors.join('\n') : undefined
     return {
-        message: errors.length > 0 ? errors.join('\n') : `Claude result ended with ${message.subtype}.`,
+        message: detail || `Claude result ended with ${message.subtype}.`,
         code: message.subtype,
     }
 }
 
-function shouldEndAssistantSnapshot(message: BetaMessage, state: ClaudeEventMapperState, actor: ClaudeSubagentActor | undefined): boolean {
-    return actor !== undefined
+function shouldEndAssistantSnapshot(message: BetaMessage, state: ClaudeEventMapperState, actor: AgentEventActor): boolean {
+    return actor.type === 'subagent'
         && !state.streamedTextByMessageId.has(message.id)
         && !state.streamedReasoningMessageIds.has(message.id)
 }
 
-function actorFromParentToolUseId(parentToolUseId: string | null, state: ClaudeEventMapperState): ClaudeSubagentActor | undefined {
-    return parentToolUseId ? state.subagentByToolCallId.get(parentToolUseId) : undefined
+function actorContextFromParentToolUseId(parentToolUseId: string | null, drafts: AgentEventDraft[], state: ClaudeEventMapperState): ClaudeActorContext | undefined {
+    if (parentToolUseId === null)
+        return { actor: mainActor, turnId: ensureTurnStarted(drafts, state) }
+
+    const actor = state.subagentByToolCallId.get(parentToolUseId)
+    const turnId = actor ? state.turnIdBySubagentId.get(actor.subagentId) : undefined
+    return actor && turnId ? { actor, turnId } : undefined
+}
+
+function subagentActorForTaskMessage(input: { subagentId: string, parentToolCallId?: string, name?: string }, state: ClaudeEventMapperState): ClaudeTaskActorResolution {
+    const existingByTask = state.subagentByTaskId.get(input.subagentId)
+    if (existingByTask) {
+        if (input.parentToolCallId && existingByTask.parentToolCallId !== input.parentToolCallId && state.subagentByToolCallId.get(input.parentToolCallId)?.subagentId !== input.subagentId)
+            return { status: 'conflict' }
+        const turnId = state.turnIdBySubagentId.get(input.subagentId)
+        if (!turnId)
+            return { status: 'conflict' }
+        const actor = actorWithObservedName(existingByTask, input.name, state)
+        return { status: 'resolved', context: { actor, turnId } }
+    }
+
+    if (!input.parentToolCallId)
+        return { status: 'pending' }
+    const existingByTool = state.subagentByToolCallId.get(input.parentToolCallId)
+    if (existingByTool)
+        return { status: existingByTool.subagentId === input.subagentId ? 'pending' : 'conflict' }
+
+    const owner = state.toolOwnerById.get(input.parentToolCallId)
+    if (!owner)
+        return { status: 'pending' }
+    if (input.subagentId === mainActor.actorId || owner.actor.actorId === input.subagentId || wouldCreateActorCycle(input.subagentId, owner.actor, state))
+        return { status: 'conflict' }
+
+    const actor = subagentActorFromTask({
+        subagentId: input.subagentId,
+        parentActorId: owner.actor.actorId,
+        parentToolCallId: input.parentToolCallId,
+        name: input.name,
+    })
+    state.subagentByTaskId.set(input.subagentId, actor)
+    state.subagentByToolCallId.set(input.parentToolCallId, actor)
+    state.turnIdBySubagentId.set(input.subagentId, owner.turnId)
+    state.runToolCallIdBySubagentId.set(input.subagentId, input.parentToolCallId)
+    return { status: 'resolved', context: { actor, turnId: owner.turnId } }
+}
+
+function actorWithObservedName(actor: ClaudeSubagentActor, name: string | undefined, state: ClaudeEventMapperState): ClaudeSubagentActor {
+    if (!name || actor.name === name)
+        return actor
+    if (actor.name)
+        return actor
+
+    const named = { ...actor, name }
+    state.subagentByTaskId.set(actor.subagentId, named)
+    if (actor.parentToolCallId)
+        state.subagentByToolCallId.set(actor.parentToolCallId, named)
+    return named
 }
 
-function subagentActorForTaskMessage(input: { subagentId: string, parentToolCallId?: string, name?: string }, state: ClaudeEventMapperState): ClaudeSubagentActor {
-    const existing = input.parentToolCallId ? state.subagentByToolCallId.get(input.parentToolCallId) : undefined
-    return existing ?? subagentActorFromTask(input)
+function wouldCreateActorCycle(subagentId: string, parent: AgentEventActor, state: ClaudeEventMapperState): boolean {
+    let actor = parent
+    const visited = new Set<string>()
+    while (actor.type === 'subagent') {
+        if (actor.actorId === subagentId || visited.has(actor.actorId))
+            return true
+        visited.add(actor.actorId)
+        const next = state.subagentByTaskId.get(actor.parentActorId)
+        if (!next)
+            return false
+        actor = next
+    }
+    return false
 }
 
-function subagentActorFromTask(input: { subagentId: string, parentToolCallId?: string, name?: string }): ClaudeSubagentActor {
+function subagentActorFromTask(input: { subagentId: string, parentActorId: string, parentToolCallId: string, name?: string }): ClaudeSubagentActor {
     return removeUndefined({
         type: 'subagent' as const,
         actorId: input.subagentId,
         subagentId: input.subagentId,
-        parentActorId: 'main',
-        origin: input.parentToolCallId ? { type: 'tool_call' as const, toolCallId: input.parentToolCallId } : { type: 'provider_task' as const, taskId: input.subagentId },
+        parentActorId: input.parentActorId,
+        origin: { type: 'tool_call' as const, toolCallId: input.parentToolCallId },
         parentToolCallId: input.parentToolCallId,
         name: input.name,
     })
 }
 
+function flushPendingMessages(state: ClaudeEventMapperState): AgentEventDraft[] {
+    const drafts: AgentEventDraft[] = []
+    let resolved = true
+    while (resolved) {
+        resolved = false
+        for (let index = 0; index < state.pendingMessages.length; index += 1) {
+            const pendingDrafts = mapClaudeMessageWithKnownActor(state.pendingMessages[index]!, state)
+            if (pendingDrafts === undefined)
+                continue
+            state.pendingMessages.splice(index, 1)
+            drafts.push(...pendingDrafts)
+            resolved = true
+            break
+        }
+    }
+    return drafts
+}
+
 function subagentPayloadRef(actor: ClaudeSubagentActor): Pick<ClaudeSubagentActor, 'actorId' | 'subagentId' | 'parentActorId' | 'origin' | 'parentToolCallId' | 'name'> {
     return removeUndefined({
         actorId: actor.actorId,
@@ -737,12 +1321,15 @@ function normalizeToolName(name: string): string {
 function usageFromObject(value: BetaUsage | undefined): AgentUsage | undefined {
     if (!value)
         return undefined
+    // Anthropic input_tokens excludes cache reads and writes; the provider-neutral inputTokens, like
+    // Codex's, counts every input token, with the cached subsets reported alongside it.
+    const inputTokens = value.input_tokens + (value.cache_read_input_tokens ?? 0) + (value.cache_creation_input_tokens ?? 0)
     return removeUndefined({
-        inputTokens: value.input_tokens,
+        inputTokens,
         outputTokens: value.output_tokens,
         cacheReadTokens: value.cache_read_input_tokens ?? undefined,
         cacheWriteTokens: value.cache_creation_input_tokens ?? undefined,
-        totalTokens: value.input_tokens + value.output_tokens + (value.cache_read_input_tokens ?? 0) + (value.cache_creation_input_tokens ?? 0),
+        totalTokens: inputTokens + value.output_tokens,
     })
 }
 
@@ -756,13 +1343,159 @@ function thinkingFromAssistantContent(content: BetaMessage['content']): string |
     return text || undefined
 }
 
-function textFromToolResultContent(content: UserToolResultBlock['content']): string | undefined {
-    if (!content)
+function correlatedHostTrailerToolCallId(input: { content: UserContentBlock[], message: ClaudeUserMessage, state: ClaudeEventMapperState }): string | undefined {
+    if (input.message.tool_use_result === undefined)
         return undefined
-    if (typeof content === 'string')
-        return content
-    const text = content.map(block => block.type === 'text' ? block.text : '').join('\n')
-    return text || undefined
+    const toolCallId = soleToolResultToolCallId(input.content)
+    return toolCallId && input.state.hostMcpToolCallIds.has(toolCallId) ? toolCallId : undefined
+}
+
+// The SDK attaches one message-level tool_use_result, so it is attributable only to a sole tool_result.
+function soleToolResultToolCallId(content: UserContentBlock[]): string | undefined {
+    const toolResults = content.filter((block): block is UserToolResultBlock => block.type === 'tool_result')
+    return toolResults.length === 1 ? toolResults[0]!.tool_use_id : undefined
+}
+
+function mappedModelToolResultContent({ content, isError }: { content: UserToolResultBlock['content'], isError: boolean }): { content: AgentToolContent[], text?: string } {
+    if (typeof content === 'string') {
+        const text = isError ? withoutToolUseErrorWrapper(content) : content
+        return { content: [{ type: 'text', text }], text }
+    }
+    if (content === undefined)
+        return { content: [] }
+    if (!Array.isArray(content)) {
+        const parsed = jsonValueSchema.safeParse(content)
+        return parsed.success ? { content: [jsonToolContent(parsed.data)] } : { content: [] }
+    }
+
+    const mapped: AgentToolContent[] = []
+    let text = ''
+    let hasText = false
+    for (const block of content) {
+        const parsed = jsonValueSchema.safeParse(block)
+        if (!parsed.success)
+            continue
+        const value = isError ? withoutToolUseErrorBlockWrapper(parsed.data) : parsed.data
+        if (isJsonObject(value) && value.type === 'text' && typeof value.text === 'string') {
+            hasText = true
+            text += value.text
+        }
+        mapped.push(modelToolContent(value))
+    }
+    return removeUndefined({ content: mapped, text: hasText ? text : undefined })
+}
+
+// Claude Code wraps its own tool failures as `<tool_use_error>…</tool_use_error>` for the model and
+// strips the same wrapper before display (CLI 2.1.280), so the wrapper is transport, not output.
+const TOOL_USE_ERROR_WRAPPER = /^<tool_use_error>([\s\S]*)<\/tool_use_error>$/
+
+function withoutToolUseErrorWrapper(text: string): string {
+    return TOOL_USE_ERROR_WRAPPER.exec(text)?.[1] ?? text
+}
+
+function withoutToolUseErrorBlockWrapper(value: JsonValue): JsonValue {
+    if (!isJsonObject(value) || value.type !== 'text' || typeof value.text !== 'string')
+        return value
+    return { ...value, text: withoutToolUseErrorWrapper(value.text) }
+}
+
+function modelToolContent(value: JsonValue): AgentToolContent {
+    if (!isJsonObject(value))
+        return jsonToolContent(value)
+    if (value.type === 'image' && isJsonObject(value.source)) {
+        const source = value.source
+        const extras = Object.fromEntries(Object.entries(value).filter(([key]) => key !== 'type' && key !== 'source'))
+        const sourceExtras = Object.fromEntries(Object.entries(source).filter(([key]) => !['type', 'media_type', 'data', 'url'].includes(key)))
+        if (Object.keys(sourceExtras).length > 0)
+            extras.source = sourceExtras
+        const metadata = Object.keys(extras).length > 0 ? { extras } : {}
+        if (source.type === 'base64' && typeof source.media_type === 'string' && source.media_type.length > 0
+            && typeof source.data === 'string' && source.data.length > 0) {
+            return { type: 'image', mimeType: source.media_type, data: source.data, ...metadata }
+        }
+        if (source.type === 'url' && typeof source.url === 'string' && source.url.length > 0)
+            return { type: 'image', uri: source.url, ...metadata }
+    }
+    return mcpToolContent(value)
+}
+
+function mappedHostMcpContent(input: { trailer: unknown, modelBlocks: AgentToolContent[] }): AgentToolContent[] {
+    const content: AgentToolContent[] = [...input.modelBlocks]
+    const hostContent = ownJsonSlot(input.trailer, 'content')
+    if (hostContent !== undefined) {
+        const hostBlocks = Array.isArray(hostContent) ? hostContent.map(mcpToolContent) : [mcpToolContent(hostContent)]
+        mergeToolContentOccurrences(content, hostBlocks)
+    }
+    const resourceLinks = ownJsonSlot(input.trailer, 'resourceLinks')
+    if (resourceLinks !== undefined) {
+        if (Array.isArray(resourceLinks))
+            mergeToolContentOccurrences(content, resourceLinks.map(resourceLinkContent))
+        else
+            content.push(jsonToolContent(resourceLinks))
+    }
+    return content
+}
+
+function mergeToolContentOccurrences(target: AgentToolContent[], incoming: AgentToolContent[]): void {
+    let cursor = 0
+    for (let incomingIndex = 0; incomingIndex < incoming.length; incomingIndex += 1) {
+        const block = incoming[incomingIndex]!
+        const index = target.findIndex((existing, position) => position >= cursor
+            && jsonValuesEqual(contentIdentity(existing), contentIdentity(block)))
+        if (index === -1) {
+            const nextMatch = target.findIndex((existing, position) => position >= cursor
+                && incoming.slice(incomingIndex + 1).some(next => jsonValuesEqual(contentIdentity(existing), contentIdentity(next))))
+            const insertion = nextMatch === -1 ? target.length : nextMatch
+            target.splice(insertion, 0, block)
+            cursor = insertion + 1
+        }
+        else {
+            cursor = index + 1
+            const existing = target[index]!
+            if (block.type !== 'json' && existing.type !== 'json') {
+                target[index] = removeUndefined({
+                    ...block,
+                    annotations: block.annotations ?? existing.annotations,
+                    extras: existing.extras || block.extras ? { ...existing.extras, ...block.extras } : undefined,
+                })
+            }
+            else {
+                target[index] = block
+            }
+        }
+    }
+}
+
+function contentIdentity(content: AgentToolContent): JsonValue {
+    return Object.fromEntries(Object.entries(content).filter(([key]) => key !== 'extras' && key !== 'annotations'))
+}
+
+function resourceLinkContent(value: JsonValue): AgentToolContent {
+    if (isJsonObject(value) && typeof value.name === 'string' && typeof value.uri === 'string')
+        return mcpToolContent({ ...value, type: 'resource_link' })
+    return jsonToolContent(value)
+}
+
+function jsonValuesEqual(left: JsonValue | undefined, right: JsonValue | undefined): boolean {
+    if (left === right)
+        return true
+    if (left === undefined || right === undefined || typeof left !== typeof right || left === null || right === null)
+        return false
+    if (Array.isArray(left) || Array.isArray(right)) {
+        if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length)
+            return false
+        return left.every((entry, index) => jsonValuesEqual(entry, right[index]))
+    }
+    if (!isJsonObject(left) || !isJsonObject(right))
+        return false
+    const leftKeys = Object.keys(left)
+    const rightKeys = Object.keys(right)
+    return leftKeys.length === rightKeys.length
+        && leftKeys.every(key => Object.hasOwn(right, key) && jsonValuesEqual(left[key], right[key]))
+}
+
+function isHostMcpToolName(name: string): boolean {
+    return name.startsWith('mcp__') && !name.startsWith(CLAUDE_RUNTIME_TOOL_PREFIX)
 }
 
 function jsonInput(value: unknown): JsonValue {