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

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

@@ -1,27 +1,39 @@
 import type { Query, SDKMessage, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk'
+import type { UUID } from 'node:crypto'
 import type {
+    AgentContextCompactionRequestResult,
     AgentError,
+    AgentNotifyCommand,
     AgentReasoningEffort,
     AgentRunMetadata,
+    AgentSettingsChange,
+    CompactContextAgentCommand,
     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 { AgentOperationOptions, AgentPromptOperationOptions } from '../agent-operation'
+import type { AgentNotificationAcceptance, AgentPromptAcceptance, AgentRun, AgentUserInputSubmission } from '../agent-run'
 import type { UserInputRequestInput, UserInputRequestStore } from '../user-input-request'
+import type { ClaudeAuthFailure } from './claude-auth'
+import type { ClaudeCodeProcess } from './claude-code-process'
 import type { ClaudeEventMapperState } from './claude-event-mapper'
+import type { ClaudeSelectedRepositoryInstructions } from './claude-selected-repository-instructions'
+import type { ClaudeSkillCatalog } from './claude-skill-catalog'
 import type { ClaudeStartupPhase } from './claude-startup-timing'
+import type { ClaudeSteeredNotificationStore, SteeredNotificationDelivery } from './claude-steered-notifications'
+import type { ClaudeWorkspaceSkills } from './claude-workspace-skills'
+import { randomUUID } from 'node:crypto'
 import z from 'zod'
 import { serializeAgentError } from '../agent-error-serializer'
 import { AgentEventStream } from '../agent-event-stream'
 import { AgentDeliveryUnknownError, AgentNotAcceptedError, AgentPromptDeferredError, AgentProviderMetadataError, AgentProviderProtocolError, AgentRunStateError } from '../agent-runtime-error'
-import { sessionConfiguredEvent } from '../agent-session-events'
+import { sessionConfiguredEvent, sessionSettingsChangedEvent } from '../agent-session-events'
 import { deriveMessageId } from '../message-id'
-import { mapClaudeUserMessage, toClaudeUserMessage } from './claude-command-mapper'
-import { mapClaudeMessage } from './claude-event-mapper'
+import { claudeNotificationText, mapClaudeUserMessage, toClaudeCompactContextMessage, toClaudeNotificationMessage, toClaudeTaskNotificationMessage, toClaudeUserMessage } from './claude-command-mapper'
+import { compactionError, flushHeldTurnEnd, mapClaudeMessage, mapSteerLifecycle, resultError } from './claude-event-mapper'
 import { hydrateClaudeToolOutput } from './claude-persisted-output'
 
 // The ONE long-lived SDK input stream created with the query. SDK 0.3.207 Query.streamInput ends
@@ -41,24 +53,39 @@ interface ClaudeInitExpectation {
     environment: Record<string, string | undefined>
 }
 
+// The model and reasoning effort a run's inputs run with; an undefined field is the CLI's default.
+interface ClaudeRunSettings {
+    model: string | undefined
+    effort: AgentReasoningEffort | undefined
+}
+
 type ClaudeInitMessage = Extract<SDKMessage, { type: 'system', subtype: 'init' }>
+type ClaudePreInitHookMessage = Extract<SDKMessage, { type: 'system', subtype: 'hook_started' | 'hook_progress' | 'hook_response' }>
 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.
+function isClaudePreInitHookMessage(message: SDKMessage | ClaudeCommandLifecycleMessage): message is ClaudePreInitHookMessage {
+    return message.type === 'system'
+        && (message.subtype === 'hook_started' || message.subtype === 'hook_progress' || message.subtype === 'hook_response')
+}
+
+// The Claude prompt-acceptance receipt is an undocumented CLI frame absent from the SDK's
+// exported SDKMessage union. Its exact shape and the original states were live-verified on SDK
+// 0.3.207 / bundled CLI 2.1.207 by scripts/smoke/claude-command-acceptance-probe.ts. CLI 2.1.263
+// added one more state, `refused`, and the pinned 0.3.280 / CLI 2.1.280 embeds the same schema,
+// which its own description defines as "declined by the session's receive-side policy before
+// entering the queue (outright, or after being held): not preceded by 'queued', and it will not
+// run in this session". Any other shape or state deviation is provider protocol drift and fails
+// the run closed. Only `queued`/`started`/`completed` are positive. `cancelled` (steered-over,
+// aborted, or user-cancelled) and `discarded` (session ended with the command still queued) are
+// observed non-positive states whose real outcome the run's close settles; `refused` is a definite
+// terminal non-acceptance while the session keeps running, so it settles the waiter itself.
 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']),
+    state: z.enum(['queued', 'started', 'completed', 'cancelled', 'discarded', 'refused']),
     uuid: z.uuid(),
 })
 
@@ -68,6 +95,51 @@ interface AcceptanceWaiter {
     reject: (error: unknown) => void
 }
 
+// The one in-flight notification (the supervisor submits commands one at a time). It settles on the
+// turn that actually consumes it: `started` on its command_lifecycle frame, then the turn identity.
+interface NotificationWaiter {
+    clientMessageId: string
+    // The main turn active when the notification was written; a fold into it is a join.
+    activeTurnIdAtSubmission: string | undefined
+    consumed: boolean
+    promise: Promise<AgentNotificationAcceptance>
+    resolve: (acceptance: AgentNotificationAcceptance) => void
+    reject: (error: unknown) => void
+}
+
+// Steered envelopes taken for a follow-up turn whose input Claude has not started yet; they return
+// to the store if Claude drops that input first.
+interface SteeredNotificationFollowUp {
+    clientMessageId: UUID
+    delivery: SteeredNotificationDelivery
+}
+
+// The one-time session context is owed until a prompt carrying it starts in Claude. A carrying
+// prompt Claude drops before starting it (cancelled, discarded, refused, or never written) owes it
+// again, so the next prompt carries it. Synthetic inputs (/compact, notifications) never carry it.
+type ClaudeSessionContextState
+    = | { status: 'owed', text: string }
+        | { status: 'carried', text: string, clientMessageId: string }
+        | { status: 'delivered' }
+
+type CommandLifecycleFrame = z.infer<typeof commandLifecycleFrameSchema>
+
+// A manual compaction reports one request result: the correlated outcome, the compaction deadline,
+// or the run's end. `compactContext` returns once Claude accepts the input, so an outcome observed
+// later is reported as it arrives, while one observed before acceptance is kept for the submitting
+// call to report and return. Reporting does not end the compaction: an accepted one stays registered,
+// deferring steers and rejecting a second compaction, until Claude ends it (its correlated outcome
+// or the end of its turn) or the run ends, even after the deadline reported `unknown`.
+interface CompactionWaiter {
+    commandId: string
+    clientMessageId: string
+    timeout: ReturnType<typeof setTimeout>
+    accepted: boolean
+    outcome?: AgentContextCompactionRequestResult
+    reported?: AgentContextCompactionRequestResult
+    boundaryObserved: boolean
+}
+
 function interruptTargetsTurn(interrupt: ClaudeEventMapperState['interrupt'], turnId: string): boolean {
     return interrupt.status !== 'none' && interrupt.turnId === turnId
 }
@@ -79,9 +151,33 @@ interface ClaudeRunInput {
     input: ClaudeInputStream
     eventMapperState: ClaudeEventMapperState
     init: ClaudeInitExpectation
+    steeredNotifications: ClaudeSteeredNotificationStore
+    // Delivered once, with the session's first prompt, then cleared (see session-context.ts).
+    sessionContext: string | undefined
+    workspace: ClaudeRunWorkspace
+    // The run's Claude Code process; the run is not reported ended until it has exited.
+    process: ClaudeRunProcess
+    onFinished: () => Promise<void>
+    compactionTimeoutMs?: number
     recordStartup?: (phase: ClaudeStartupPhase) => void
+    // Reads SDK-persisted tool results back from the transcript so tool events carry full output.
+    hydratePersistedToolOutput?: boolean
+}
+
+type ClaudeRunProcess = Pick<ClaudeCodeProcess, 'terminate' | 'stderrTail'>
+
+// The run's workspace registration: the generated skills plugin, the repository roots it links,
+// the catalog fed from the CLI's command list, and the managed selected-repository instructions.
+interface ClaudeRunWorkspace {
+    // Absent when the provider generates no workspace skills plugin.
+    skills?: ClaudeWorkspaceSkills
+    repositoryRoots: readonly string[]
+    catalog: ClaudeSkillCatalog
+    instructions: ClaudeSelectedRepositoryInstructions
 }
 
+export const CLAUDE_COMPACTION_TIMEOUT_MS = 180_000
+
 export class ClaudeRun implements AgentRun {
     readonly events: AgentEventStream
     readonly metadata: AgentRunMetadata
@@ -90,30 +186,75 @@ export class ClaudeRun implements AgentRun {
     private readonly input: ClaudeInputStream
     private readonly eventMapperState: ClaudeEventMapperState
     private readonly init: ClaudeInitExpectation
-    private readonly recordStartup: ClaudeRunInput['recordStartup']
-    private readonly initialization: Promise<void>
-    private initializationResolve: () => void = () => undefined
+    private readonly workspaceSkills: ClaudeWorkspaceSkills | undefined
+    private readonly selectedRepositoryInstructions: ClaudeSelectedRepositoryInstructions
+    private readonly steeredNotifications: ClaudeSteeredNotificationStore
+    private sessionContext: ClaudeSessionContextState
+    private readonly skillCatalog: ClaudeSkillCatalog
+    private workspaceRepositoryRoots: readonly string[]
+    // Set when the skills plugin changed on disk and cleared only by a successful reload, so a
+    // repository root whose reload was aborted or failed is reloaded again on retry.
+    private skillReloadOwed = false
+    private readonly process: ClaudeRunProcess
+    private readonly onFinished: () => Promise<void>
+    private readonly compactionTimeoutMs: number
+    // Settles after the CLI has exited and the terminal events are pushed (set by finish).
+    private ended: Promise<void> | undefined
+    // Resolves with the model system/init reported: the CLI default when no model was requested.
+    private readonly initialization: Promise<string>
+    private initializationResolve: (model: string) => void = () => undefined
     private initializationReject: (error: unknown) => void = () => undefined
     private initialized = false
+    // With CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS the CLI reports `running` for the first input before
+    // system/init; those frames are held and mapped right after init so the turn starts on time.
+    private readonly preInitSessionStates: SDKMessage[] = []
     private firstInputPushed = false
-    private pendingSteerResult?: Extract<SDKMessage, { type: 'result' }>
-    private modelChangeReady = true
-    private modelChangeInFlight = false
     private finished = false
+    private queryClosed = false
     private interruptRequest?: { turnId: string, promise: Promise<void> }
     private readonly acceptanceWaiters = new Map<string, AcceptanceWaiter>()
+    // Client message ids of steering (`now`) prompts whose lifecycle can supersede the running ask.
+    private readonly steerInputIds = new Set<string>()
+    private compactionWaiter?: CompactionWaiter
+    private notificationWaiter?: NotificationWaiter
+    private steeredFollowUp?: SteeredNotificationFollowUp
+    private readonly recordStartup: ClaudeRunInput['recordStartup']
+    private readonly hydratePersistedToolOutput: boolean
+    private modelChangeReady = true
+    private modelChangeInFlight = false
+    // Provider command identity by derived client message id, until its completed/negative receipt.
     private readonly commandByClientMessageId = new Map<string, string>()
+    // Prompts whose accepted user message has not been emitted into a turn yet.
     private readonly pendingMessages = new Map<string, { messageId: string, mode: 'next' | 'steer', turnId?: string, started: boolean }>()
 
-    constructor({ metadata, query, userInputRequests, input, eventMapperState, init, recordStartup }: ClaudeRunInput) {
+    // The accepted settings: they change only once the input carrying a change is accepted.
+    private current: ClaudeRunSettings
+    // What the CLI was last told, or undefined when a failed control request left it unknown. It
+    // differs from `current` only after a change reached the CLI for an input that was then not
+    // written or not accepted; every input re-asserts `current` before it is written.
+    private providerApplied: ClaudeRunSettings | undefined
+
+    constructor({ metadata, query, userInputRequests, input, eventMapperState, init, steeredNotifications, sessionContext, workspace, process, onFinished, compactionTimeoutMs = CLAUDE_COMPACTION_TIMEOUT_MS, recordStartup, hydratePersistedToolOutput = true }: ClaudeRunInput) {
         this.metadata = metadata
         this.query = query
         this.userInputRequests = userInputRequests
         this.input = input
         this.eventMapperState = eventMapperState
         this.init = init
+        this.workspaceSkills = workspace.skills
+        this.selectedRepositoryInstructions = workspace.instructions
+        this.steeredNotifications = steeredNotifications
+        this.sessionContext = sessionContext === undefined ? { status: 'delivered' } : { status: 'owed', text: sessionContext }
+        this.skillCatalog = workspace.catalog
+        this.workspaceRepositoryRoots = [...workspace.repositoryRoots]
+        this.process = process
+        this.onFinished = onFinished
+        this.compactionTimeoutMs = compactionTimeoutMs
         this.recordStartup = recordStartup
-        this.initialization = new Promise<void>((resolve, reject) => {
+        this.hydratePersistedToolOutput = hydratePersistedToolOutput
+        this.current = { model: init.requestedModel, effort: init.reasoningEffort }
+        this.providerApplied = this.current
+        this.initialization = new Promise<string>((resolve, reject) => {
             this.initializationResolve = resolve
             this.initializationReject = reject
         })
@@ -129,9 +270,10 @@ export class ClaudeRun implements AgentRun {
     // 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.
+    // legitimately precedes system/init. SDK-declared SessionStart/Setup hook lifecycle frames may
+    // also precede init; they are session-validated and discarded so hook output stays private.
+    // PRE_INIT is otherwise strict: the next message must be a matching system/init, and the run's
+    // own session lifecycle AgentEvents are emitted only after that init validation.
     begin(): void {
         void this.consume()
     }
@@ -139,6 +281,8 @@ export class ClaudeRun implements AgentRun {
     pushEvent(draft: AgentEventDraft): void {
         if (this.finished)
             return
+        if (draft.type === 'turn.started' && draft.actor.type === 'main')
+            this.settleNotificationTurn(draft.turnId)
         if (draft.type === 'turn.started')
             this.modelChangeReady = false
         if (draft.type === 'session.state.changed' && draft.payload.state === 'idle')
@@ -153,6 +297,8 @@ export class ClaudeRun implements AgentRun {
             this.emitAcceptedMessage(draft.payload.commandId, draft.turnId)
     }
 
+    // The accepted input becomes a user message of the turn that consumed it, correlated with the
+    // command that carried it, once the native started receipt confirmed that turn.
     private emitAcceptedMessage(commandId: string, turnId: string): void {
         const pending = this.pendingMessages.get(commandId)
         if (!pending?.started || !this.initialized || this.finished)
@@ -172,65 +318,416 @@ export class ClaudeRun implements AgentRun {
         return { requestId: request.requestId }
     }
 
+    // Codex registers repository skill roots at this barrier; Claude re-links the run's workspace
+    // skills plugin now that the Git baseline exists and always refreshes the catalog once.
     async prepareWorkspace(options: AgentOperationOptions = {}): Promise<void> {
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        if (!this.workspaceSkills)
+            return
+        await this.workspaceSkills.sync(this.workspaceRepositoryRoots)
         options.signal?.throwIfAborted()
+        await this.reloadSkills()
     }
 
-    // Claude discovers repository guidance from the filesystem; there is no provider-side root registry.
-    async addWorkspaceRepositoryRoot(_root: string, options: AgentOperationOptions = {}): Promise<void> {
+    async addWorkspaceRepositoryRoot(root: string, options: AgentOperationOptions = {}): Promise<void> {
+        this.assertRunning()
         options.signal?.throwIfAborted()
+        if (this.workspaceRepositoryRoots.includes(root))
+            return
+        const repositoryRoots = [...this.workspaceRepositoryRoots, root]
+        await this.selectedRepositoryInstructions.update(repositoryRoots)
+        if (await this.workspaceSkills?.sync(repositoryRoots))
+            this.skillReloadOwed = true
+        options.signal?.throwIfAborted()
+        if (this.skillReloadOwed)
+            await this.reloadSkills()
+        // Recorded last: a retry after an abort or failure above redoes the registration.
+        this.workspaceRepositoryRoots = repositoryRoots
+    }
+
+    // Claude Code re-reads plugin skill directories only on reload; the response carries the
+    // refreshed command list, which is authoritative for the catalog.
+    private async reloadSkills(): Promise<void> {
+        const reloaded = await this.query.reloadPlugins()
+        this.skillCatalog.publish(reloaded.commands)
+        this.skillReloadOwed = false
     }
 
-    async sendPrompt(command: SendPromptCommand, options: AgentOperationOptions = {}): Promise<AgentPromptAcceptance> {
+    async sendPrompt(command: SendPromptCommand, options: AgentPromptOperationOptions = {}): Promise<AgentPromptAcceptance> {
         this.assertCommandTargetsRun(command)
         this.assertRunning()
         options.signal?.throwIfAborted()
+        if (options.submissionOrder === 'bypass' && command.mode === 'next') {
+            throw new AgentRunStateError({
+                message: 'Bypass submission requires a steer prompt.',
+            })
+        }
         if (command.reasoningEffort !== undefined && command.reasoningEffort !== this.init.reasoningEffort)
             throw new AgentNotAcceptedError({ message: 'Claude reasoning effort changes are not supported by this adapter.', recovery: { kind: 'terminal', reason: 'reasoning_effort_change_not_supported' } })
-        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()
+        // Claude Code steers by cancelling the running ask, which would abort a manual compaction
+        // (CLI 2.1.280). Like Codex's non-steerable compaction turn, the steer waits for it to end.
+        if (command.mode === 'steer' && this.compactionWaiter) {
+            throw new AgentPromptDeferredError({
+                message: 'Claude is compacting context; a steer would cancel the compaction.',
+            })
+        }
+        const settings = this.settingsWith(command.settings)
+        // Captured before the change: Claude applies it from the next model request, so a turn
+        // running now is the one it enters. With no running turn, the input starts a turn whose id
+        // does not exist yet. Either way the turn that handles this input runs on the new settings.
+        const turnIdAtSubmission = this.eventMapperState.currentTurnId
+        const clientMessageId = deriveMessageId(command.commandId)
+        // Claimed before the asynchronous mapping so a concurrent prompt cannot carry it too.
+        const sessionContext = this.carrySessionContext(clientMessageId)
+        try {
+            const input = { prompt: command.prompt, mode: command.mode, commandId: command.commandId, origin: command.origin, author: command.author, senderContext: options.senderContext, authorContext: options.authorContext, sessionContext }
+            const message = await mapClaudeUserMessage(input, options.inputAttachmentPreparation)
+            options.signal?.throwIfAborted()
+            if (command.model || this.modelChangeInFlight)
+                await this.applyCommandModel(command, options)
+            if (command.turnId && (command.mode !== 'steer' || command.turnId !== this.eventMapperState.currentTurnId))
+                throw new AgentNotAcceptedError({ message: 'The targeted claude turn is no longer active.', recovery: { kind: 'terminal', reason: 'target_turn_not_active' } })
+            this.modelChangeReady = false
+            await this.applyProviderSettings(command.settings ? settings : this.current)
+            // 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 receipt = this.registerAcceptanceWaiter(clientMessageId)
+            if (command.origin === 'user')
+                this.eventMapperState.promptCommandByInputId.set(clientMessageId, command.commandId)
+            this.commandByClientMessageId.set(clientMessageId, command.commandId)
+            this.pendingMessages.set(command.commandId, { messageId: clientMessageId, mode: command.mode, turnId: command.turnId, started: false })
+            if (command.mode === 'steer')
+                this.steerInputIds.add(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)
+            }
+        }
+        catch (error) {
+            if (error instanceof AgentNotAcceptedError)
+                this.eventMapperState.promptCommandByInputId.delete(clientMessageId)
+            if (sessionContext !== undefined)
+                this.releaseSessionContext(clientMessageId)
+            throw error
+        }
+        if (command.settings) {
+            this.current = settings
+            this.pushEvent(sessionSettingsChangedEvent({
+                model: settings.model ?? await this.initialization,
+                reasoningEffort: settings.effort,
+                commandId: command.commandId,
+                turnId: turnIdAtSubmission,
+                appliesFrom: 'current_turn',
+            }))
+        }
+        return { kind: 'submitted' }
+    }
+
+    // Applies an application-resolved model through the control channel before the input. Changes
+    // wait for an idle boundary with no accepted input still pending, so they never reconfigure a
+    // queued prompt. Reapplying the same resolved model after a crash is safe.
+    private async applyCommandModel(command: SendPromptCommand, options: AgentOperationOptions): Promise<void> {
         if (this.modelChangeInFlight)
             throw new AgentPromptDeferredError({ message: 'Claude model configuration is still in progress.' })
         const currentModel = this.init.requestedModel ?? this.metadata.model
-        if (command.model && command.model !== currentModel) {
-            if (!this.modelChangeReady || this.eventMapperState.currentTurnId || this.commandByClientMessageId.size > 0)
-                throw new AgentPromptDeferredError({ message: 'Claude model changes require an idle turn boundary.' })
-            // The control receipt must precede the input. Reapplying the same resolved model
-            // after a crash is safe; never retry an uncertain prompt to retry configuration.
-            this.modelChangeInFlight = true
-            try {
-                await this.query.setModel(command.model)
+        if (!command.model || command.model === currentModel)
+            return
+        if (!this.modelChangeReady || this.eventMapperState.currentTurnId || this.commandByClientMessageId.size > 0)
+            throw new AgentPromptDeferredError({ message: 'Claude model changes require an idle turn boundary.' })
+        this.modelChangeInFlight = true
+        try {
+            await this.query.setModel(command.model)
+        }
+        finally {
+            this.modelChangeInFlight = false
+        }
+        this.metadata.model = command.model
+        this.init.requestedModel = command.model
+        this.current = { ...this.current, model: command.model }
+        this.providerApplied = this.current
+        options.signal?.throwIfAborted()
+    }
+
+    // Model admission belongs to the product; core accepts its resolved provider model ID.
+    private settingsWith(change: AgentSettingsChange | undefined): ClaudeRunSettings {
+        if (change === undefined)
+            return this.current
+        return {
+            model: change.model ?? this.current.model,
+            effort: change.reasoningEffort ?? this.current.effort,
+        }
+    }
+
+    // The SDK user message cannot carry a model or effort, so they go as control requests, which
+    // take effect from the CLI's next model request, even inside a running turn. Both are awaited
+    // before the input is written: a steer pushed first was observed making its first request with
+    // the new model but the old effort (CLI 2.1.280). A failure proves the input was not written,
+    // but not what the CLI kept, so the next input re-applies both.
+    private async applyProviderSettings(settings: ClaudeRunSettings): Promise<void> {
+        const known = this.providerApplied
+        this.providerApplied = undefined
+        try {
+            if (known === undefined || known.model !== settings.model)
+                await this.query.setModel(settings.model)
+            if (known === undefined || known.effort !== settings.effort)
+                await this.query.applyFlagSettings({ effortLevel: settings.effort ?? null })
+        }
+        catch (error) {
+            throw new AgentNotAcceptedError({
+                message: 'Claude did not apply the model or reasoning effort; the input was not written.',
+                recovery: { kind: 'retry', reason: 'provider_settings_not_applied' },
+                cause: error,
+            })
+        }
+        this.providerApplied = settings
+    }
+
+    private carrySessionContext(clientMessageId: string): string | undefined {
+        if (this.sessionContext.status !== 'owed')
+            return undefined
+        this.sessionContext = { status: 'carried', text: this.sessionContext.text, clientMessageId }
+        return this.sessionContext.text
+    }
+
+    private releaseSessionContext(clientMessageId: string): void {
+        if (this.sessionContext.status === 'carried' && this.sessionContext.clientMessageId === clientMessageId)
+            this.sessionContext = { status: 'owed', text: this.sessionContext.text }
+    }
+
+    // `started`/`completed` mean the model received the carrying prompt. A later `cancelled` (an
+    // aborted turn cancels the inputs it already started) no longer finds it carried.
+    private observeSessionContextLifecycle(frame: CommandLifecycleFrame): void {
+        if (this.sessionContext.status !== 'carried' || this.sessionContext.clientMessageId !== frame.command_uuid)
+            return
+        if (frame.state === 'started' || frame.state === 'completed')
+            this.sessionContext = { status: 'delivered' }
+        else if (frame.state !== 'queued')
+            this.releaseSessionContext(frame.command_uuid)
+    }
+
+    // Mirrors CodexRun.notify's observable contract: an idle session starts a turn with the
+    // notification, and an active main turn is joined. Claude Code has no mid-turn input channel, so
+    // a joined notification is written to the session-local steered-notification store before the
+    // `steered` receipt and delivered inside that turn by the run's hooks (next main tool boundary,
+    // or a Stop-hook continuation when the turn would otherwise end), or, when it lands after that
+    // Stop hook passed, by a follow-up turn. See claude-steered-notifications.ts.
+    async notify(command: AgentNotifyCommand, options: AgentOperationOptions = {}): Promise<AgentNotificationAcceptance> {
+        this.assertCommandTargetsRun(command)
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        if (this.userInputRequests.hasUnresolvedUserInput()) {
+            throw new AgentPromptDeferredError({
+                message: 'Claude is waiting for unresolved user input; a notification cannot be submitted.',
+            })
+        }
+        const activeTurnId = this.eventMapperState.currentTurnId
+        if (activeTurnId) {
+            if (interruptTargetsTurn(this.eventMapperState.interrupt, activeTurnId)) {
+                throw new AgentPromptDeferredError({
+                    message: 'Claude is interrupting the active turn; the notification waits for the next idle boundary.',
+                })
             }
-            finally {
-                this.modelChangeInFlight = false
+            const queued = this.steeredNotifications.enqueue({ commandId: command.commandId, turnId: activeTurnId, text: claudeNotificationText(command) })
+            return { kind: 'turn', turnId: queued.kind === 'duplicate' ? queued.turnId : activeTurnId, placement: 'steered' }
+        }
+        if (this.notificationWaiter)
+            throw new AgentRunStateError({ message: 'A Claude notification is already awaiting its turn.' })
+        const message = toClaudeNotificationMessage(command)
+        const waiter = this.registerNotificationWaiter(deriveMessageId(command.commandId))
+        try {
+            await this.applyProviderSettings(this.current)
+            await this.deliverInput(message)
+            return await waiter.promise
+        }
+        finally {
+            if (this.notificationWaiter === waiter)
+                this.notificationWaiter = undefined
+        }
+    }
+
+    private registerNotificationWaiter(clientMessageId: string): NotificationWaiter {
+        if (this.finished)
+            throw new AgentRunStateError({ message: 'Claude run has stopped.' })
+        const { promise, resolve, reject } = Promise.withResolvers<AgentNotificationAcceptance>()
+        promise.catch(() => undefined)
+        const waiter: NotificationWaiter = {
+            clientMessageId,
+            activeTurnIdAtSubmission: this.eventMapperState.currentTurnId,
+            consumed: false,
+            promise,
+            resolve,
+            reject,
+        }
+        this.notificationWaiter = waiter
+        return waiter
+    }
+
+    // Runs on the notification's command_lifecycle frame. `started`/`completed` mean a turn consumed
+    // it: the active turn when it was folded in, else the turn about to be reported by the mapper.
+    private settleNotificationLifecycle(waiter: NotificationWaiter, state: CommandLifecycleFrame['state']): void {
+        if (state === 'queued')
+            return
+        if (state === 'refused') {
+            this.notificationWaiter = undefined
+            waiter.reject(new AgentNotAcceptedError({
+                message: 'Claude declined the notification before queueing it; it will not run in this session.',
+                recovery: { kind: 'terminal', reason: 'provider_refused' },
+            }))
+            return
+        }
+        if (state === 'cancelled' || state === 'discarded') {
+            if (!waiter.consumed) {
+                this.notificationWaiter = undefined
+                waiter.reject(new AgentDeliveryUnknownError({
+                    message: `Claude ${state} the notification before a turn was observed consuming it.`,
+                }))
             }
-            this.metadata.model = command.model
-            this.init.requestedModel = command.model
-            options.signal?.throwIfAborted()
+            return
+        }
+        if (waiter.consumed)
+            return
+        waiter.consumed = true
+        const activeTurnId = this.eventMapperState.currentTurnId
+        if (activeTurnId)
+            this.settleNotificationTurn(activeTurnId)
+    }
+
+    // A notify joined to a turn whose Stop hook already passed has no hook left in that turn. As in
+    // Codex, where such a steer starts a new turn, a completed main turn that leaves envelopes
+    // pending starts one follow-up turn delivering them. Interrupted and failed turns, and a session
+    // waiting for user input, keep them for the next input. At most one follow-up is in flight: its
+    // own UserPromptSubmit hook takes envelopes that arrive before it starts, so this cannot loop.
+    // Envelopes recovered from disk at open do not start a turn by themselves: the supervisor resumes
+    // a run only to dispatch an input, whose UserPromptSubmit hook carries them (a `/compact` input
+    // skips that hook, but its completed turn reaches this follow-up), and a prewarmed or resumed run
+    // must not reach the model on its own before its first input.
+    private async startSteeredNotificationFollowUp(): Promise<void> {
+        if (this.finished || this.steeredFollowUp || this.userInputRequests.hasUnresolvedUserInput())
+            return
+        const delivery = this.steeredNotifications.takePending()
+        if (!delivery)
+            return
+        const followUp: SteeredNotificationFollowUp = { clientMessageId: randomUUID(), delivery }
+        this.steeredFollowUp = followUp
+        try {
+            await this.pushOwnedStream(toClaudeTaskNotificationMessage({ text: delivery.text, uuid: followUp.clientMessageId }))
+        }
+        catch (error) {
+            // A rejected push provably wrote nothing.
+            this.steeredFollowUp = undefined
+            this.steeredNotifications.restore(delivery)
+            throw error
+        }
+    }
+
+    // `started`/`completed` mean the model received the envelopes. A non-positive state before that
+    // means Claude will never run the input, so the envelopes go back to the store for the next
+    // input instead of being lost. A run that ends before either keeps them delivered: like a hook
+    // hand-off, the input most likely already started.
+    private settleSteeredFollowUp(followUp: SteeredNotificationFollowUp, state: CommandLifecycleFrame['state']): void {
+        if (state === 'queued')
+            return
+        this.steeredFollowUp = undefined
+        if (state === 'cancelled' || state === 'discarded' || state === 'refused')
+            this.steeredNotifications.restore(followUp.delivery)
+    }
+
+    private settleNotificationTurn(turnId: string): void {
+        const waiter = this.notificationWaiter
+        if (!waiter?.consumed)
+            return
+        this.notificationWaiter = undefined
+        waiter.resolve({
+            kind: 'turn',
+            turnId,
+            placement: turnId === waiter.activeTurnIdAtSubmission ? 'steered' : 'started',
+        })
+    }
+
+    async compactContext(command: CompactContextAgentCommand, options: AgentOperationOptions = {}): Promise<AgentContextCompactionRequestResult> {
+        this.assertCommandTargetsRun(command)
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        if (this.eventMapperState.currentTurnId) {
+            throw new AgentPromptDeferredError({
+                message: 'Claude context compaction must wait for an idle main thread.',
+            })
         }
-        if (command.turnId && (command.mode !== 'steer' || command.turnId !== this.eventMapperState.currentTurnId))
-            throw new AgentNotAcceptedError({ message: 'The targeted claude turn is no longer active.', recovery: { kind: 'terminal', reason: 'target_turn_not_active' } })
-        this.modelChangeReady = false
-        // 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.
+        if (this.compactionWaiter)
+            throw new AgentRunStateError({ message: 'A Claude context compaction request is already pending.' })
+
+        // The deadline bounds the whole request: it cancels a submission still awaiting delivery or
+        // acceptance, and reports `unknown` for an accepted compaction whose outcome never arrived.
+        const deadline = new AbortController()
+        const operationSignal = options.signal
+            ? AbortSignal.any([options.signal, deadline.signal])
+            : deadline.signal
         const clientMessageId = deriveMessageId(command.commandId)
         const receipt = this.registerAcceptanceWaiter(clientMessageId)
-        this.commandByClientMessageId.set(clientMessageId, command.commandId)
-        this.pendingMessages.set(command.commandId, { messageId: clientMessageId, mode: command.mode, turnId: command.turnId, started: false })
+        const waiter = this.registerCompactionWaiter({ commandId: command.commandId, clientMessageId, deadline })
         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
+            await this.applyProviderSettings(this.current)
+            await this.awaitPossiblyDeliveredCompaction(
+                this.deliverInput(toClaudeCompactContextMessage(command.commandId)),
+                operationSignal,
+            )
+            await this.awaitPossiblyDeliveredCompaction(receipt.promise, operationSignal)
+        }
+        catch (error) {
+            if (!(error instanceof AgentDeliveryUnknownError)) {
+                this.releaseCompactionWaiter(waiter)
+                throw error
+            }
+            // Not accepted: the input may never have reached Claude, so holding the guard could defer
+            // steers indefinitely.
+            return this.endCompaction(waiter, { status: 'unknown' })
         }
         finally {
             this.acceptanceWaiters.delete(clientMessageId)
         }
-        return { kind: 'submitted' }
+        // Accepted: the compaction runs as a Claude turn whose events stream while it runs. Waiting
+        // for its outcome here would hold the caller, and every event queued behind it, for the
+        // whole compaction. An outcome Claude already reported is definitive; otherwise `unknown`
+        // tells the caller a turn is starting, and the outcome is reported when it arrives.
+        waiter.accepted = true
+        if (waiter.outcome)
+            return this.endCompaction(waiter, waiter.outcome)
+        return { status: 'unknown' }
+    }
+
+    private async awaitPossiblyDeliveredCompaction<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+        if (signal.aborted) {
+            throw new AgentDeliveryUnknownError({
+                message: 'Claude context compaction was cancelled after delivery may have begun.',
+                cause: signal.reason,
+            })
+        }
+        return await new Promise<T>((resolve, reject) => {
+            const aborted = (): void => {
+                reject(new AgentDeliveryUnknownError({
+                    message: 'Claude context compaction was cancelled after delivery may have begun.',
+                    cause: signal.reason,
+                }))
+            }
+            const settle = (continuation: () => void): void => {
+                signal.removeEventListener('abort', aborted)
+                continuation()
+            }
+            signal.addEventListener('abort', aborted, { once: true })
+            promise.then(
+                value => settle(() => resolve(value)),
+                error => settle(() => reject(error)),
+            )
+        })
     }
 
     async respondUserInput(command: RespondUserInputAgentCommand, options: AgentOperationOptions = {}): Promise<AgentUserInputSubmission> {
@@ -242,6 +739,7 @@ export class ClaudeRun implements AgentRun {
             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.applyProviderSettings(this.current)
         await this.deliverInput(toClaudeUserMessage({ prompt: resolved.prompt, mode: 'next', commandId: command.commandId }))
         if (resolved.event)
             this.pushEvent(resolved.event)
@@ -254,6 +752,7 @@ export class ClaudeRun implements AgentRun {
         this.assertRunning()
         options.signal?.throwIfAborted()
         const turnId = this.eventMapperState.currentTurnId
+        // A targeted interrupt never affects a replacement turn.
         if (command.turnId && command.turnId !== turnId)
             return
         if (!turnId)
@@ -292,36 +791,141 @@ export class ClaudeRun implements AgentRun {
     async stop(command: StopAgentCommand, options: AgentOperationOptions = {}): Promise<void> {
         this.assertCommandTargetsRun(command)
         options.signal?.throwIfAborted()
-        if (this.finished)
+        // A run that already ended still resolves only after its CLI has exited, so a following
+        // resume never overlaps it on the same transcript.
+        if (this.finished) {
+            await this.ended
             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')
+        await this.ended
+    }
+
+    // Mirrors CodexRun: a central credential failure is terminal for this run. The typed turn
+    // reason lets the supervisor recover owed work instead of observing a generic 401 result.
+    failActiveTurnAndEndRun(input: ClaudeAuthFailure): void {
+        // A run without input (an idle prewarm) made no model request, so the failure is not its
+        // own; ending it would leave a finished run for the supervisor to adopt. Its first request
+        // acquires a fresh credential and reports that outcome instead.
+        if (this.finished || !this.firstInputPushed)
+            return
+        this.pushEvent({ type: 'error', payload: { message: 'Claude authentication failed.', fatal: false, source: 'provider', error: input.error } })
+        const turnId = this.eventMapperState.currentTurnId
+        this.eventMapperState.heldTurnEnd = undefined
+        if (turnId) {
+            this.pushEvent({
+                type: 'turn.ended',
+                turnId,
+                actor: { type: 'main', actorId: 'main' },
+                payload: { status: 'failed', reason: input.reason, error: input.error },
+            })
+            this.eventMapperState.currentTurnId = undefined
+        }
+        if (!this.initialized)
+            this.initializationReject(new AgentRunStateError({ message: 'Claude authentication failed before initialization.' }))
+        this.closeQuery()
+        this.finish('failed', input.error)
     }
 
     finish(reason: 'completed' | 'stopped' | 'interrupted' | 'failed', error?: AgentError): void {
         if (this.finished)
             return
+        const compaction = this.compactionWaiter
+        if (compaction)
+            this.endCompaction(compaction, { status: 'unknown' })
+        // A superseded turn's steer can no longer continue it once the run ends.
+        for (const draft of flushHeldTurnEnd(this.eventMapperState)) this.pushEvent(draft)
         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.`,
+                cause: error,
             }))
         }
         this.acceptanceWaiters.clear()
+        this.eventMapperState.promptCommandByInputId.clear()
         this.commandByClientMessageId.clear()
         this.pendingMessages.clear()
+        const notification = this.notificationWaiter
+        this.notificationWaiter = undefined
+        notification?.reject(new AgentDeliveryUnknownError({
+            message: `Claude run ended (${reason}) before a turn was observed consuming the notification.`,
+            cause: error,
+        }))
+        this.ended = this.endAfterProcessExit(reason, error)
+    }
+
+    // session.ended means the CLI is gone: the terminal events wait for its exit (bounded by
+    // CLAUDE_PROCESS_EXIT_TIMEOUT_MS, then a process-group kill). close() is idempotent and sends
+    // the stdin EOF the CLI exits on.
+    private async endAfterProcessExit(reason: 'completed' | 'stopped' | 'interrupted' | 'failed', error: AgentError | undefined): Promise<void> {
+        this.closeQuery()
+        await this.process.terminate()
         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()
+        void this.onFinished().catch(() => undefined)
+    }
+
+    // Reports the request's one result; later calls return the reported one. The caller decides
+    // whether the compaction has ended and releases the waiter.
+    private reportCompactionResult(waiter: CompactionWaiter, result: AgentContextCompactionRequestResult): AgentContextCompactionRequestResult {
+        if (waiter.reported)
+            return waiter.reported
+        waiter.reported = result
+        clearTimeout(waiter.timeout)
+        this.pushEvent({
+            type: 'context.compaction.request.completed',
+            payload: { commandId: waiter.commandId, result },
+        })
+        return result
+    }
+
+    private endCompaction(waiter: CompactionWaiter, result: AgentContextCompactionRequestResult): AgentContextCompactionRequestResult {
+        const reported = this.reportCompactionResult(waiter, result)
+        this.releaseCompactionWaiter(waiter)
+        return reported
+    }
+
+    private releaseCompactionWaiter(waiter: CompactionWaiter): void {
+        clearTimeout(waiter.timeout)
+        if (this.compactionWaiter === waiter)
+            this.compactionWaiter = undefined
+    }
+
+    // First outcome wins. Before acceptance the submitting call reports it (see compactContext).
+    private settleCompaction(waiter: CompactionWaiter, outcome: AgentContextCompactionRequestResult): void {
+        waiter.outcome ??= outcome
+        if (waiter.accepted)
+            this.endCompaction(waiter, waiter.outcome)
+    }
+
+    private registerCompactionWaiter({ commandId, clientMessageId, deadline }: { commandId: string, clientMessageId: string, deadline: AbortController }): CompactionWaiter {
+        if (this.compactionWaiter)
+            throw new AgentRunStateError({ message: 'A Claude context compaction request is already pending.' })
+        const waiter: CompactionWaiter = {
+            commandId,
+            clientMessageId,
+            timeout: setTimeout(() => {
+                // Before acceptance the abort makes the submitting call report and release. After it,
+                // Claude may still be compacting: the result becomes `unknown`, the guard stays.
+                deadline.abort(new Error(`Claude context compaction exceeded ${this.compactionTimeoutMs}ms.`))
+                if (waiter.accepted)
+                    this.reportCompactionResult(waiter, { status: 'unknown' })
+            }, this.compactionTimeoutMs),
+            accepted: false,
+            boundaryObserved: false,
+        }
+        waiter.timeout.unref?.()
+        this.compactionWaiter = waiter
+        return waiter
     }
 
-    // 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.' })
@@ -341,26 +945,16 @@ export class ClaudeRun implements AgentRun {
 
     // 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 hasPendingSteer(): boolean {
-        return [...this.pendingMessages.values()].some(pending => pending.mode === 'steer'
-            && (!pending.turnId || pending.turnId === this.eventMapperState.currentTurnId))
-    }
-
-    private flushSteerResult(continueTurn = false): void {
-        const result = this.pendingSteerResult
-        this.pendingSteerResult = undefined
-        if (result) {
-            for (const draft of mapClaudeMessage(result, this.eventMapperState, { continueTurn }))
-                this.pushEvent(draft)
-        }
-    }
-
-    private settleAcceptance(frame: ClaudeCommandLifecycleMessage): void {
+    // and `discarded` are valid non-positive states that are validated and no-op even when a
+    // waiter is pending: the pending prompt's real outcome is settled by run close/error as
+    // delivery-unknown. `refused` is the pinned runtime's definite pre-queue rejection: the input
+    // will never run in this session, and the session stays open, so the pending waiter is
+    // rejected as a terminal not-accepted outcome instead of waiting for a close that may not
+    // come. Valid positive frames without a pending waiter are internal lifecycle for
+    // already-settled or non-prompt inputs and are ignored. The synthetic `/compact` input is the
+    // exception: every negative state for its uuid settles the pending compaction as `failed`, because
+    // the request has a definite result to report while the session keeps running.
+    private settleAcceptance(frame: ClaudeCommandLifecycleMessage): AgentEventDraft[] {
         const parsed = commandLifecycleFrameSchema.safeParse(frame)
         if (!parsed.success) {
             throw new AgentProviderProtocolError({
@@ -374,40 +968,130 @@ export class ClaudeRun implements AgentRun {
                 details: { expected: this.metadata.providerSessionId, actual: parsed.data.session_id },
             })
         }
-        const commandId = this.commandByClientMessageId.get(parsed.data.command_uuid)
-        if (parsed.data.state === 'cancelled' || parsed.data.state === 'discarded') {
+        this.observeSessionContextLifecycle(parsed.data)
+        const steerDrafts = this.observeSteerLifecycle(parsed.data)
+        this.settleInputLifecycle(parsed.data)
+        return steerDrafts
+    }
+
+    // A steer's receipts before system/init belong to the session's first input, which supersedes
+    // nothing; afterwards they drive the mapper's supersession of the running ask.
+    private observeSteerLifecycle(frame: CommandLifecycleFrame): AgentEventDraft[] {
+        if (!this.steerInputIds.has(frame.command_uuid))
+            return []
+        if (frame.state !== 'queued' && frame.state !== 'started')
+            this.steerInputIds.delete(frame.command_uuid)
+        if (!this.initialized)
+            return []
+        return mapSteerLifecycle({ steerId: frame.command_uuid, state: frame.state }, this.eventMapperState)
+    }
+
+    private settleInputLifecycle(frame: CommandLifecycleFrame): void {
+        const followUp = this.steeredFollowUp
+        if (followUp?.clientMessageId === frame.command_uuid) {
+            this.settleSteeredFollowUp(followUp, frame.state)
+            return
+        }
+        const notification = this.notificationWaiter
+        if (notification?.clientMessageId === frame.command_uuid) {
+            this.settleNotificationLifecycle(notification, frame.state)
+            return
+        }
+        const waiter = this.acceptanceWaiters.get(frame.command_uuid)
+        const commandId = this.commandByClientMessageId.get(frame.command_uuid)
+        if (frame.state === 'cancelled' || frame.state === 'discarded' || frame.state === 'refused') {
+            this.commandByClientMessageId.delete(frame.command_uuid)
             if (commandId)
                 this.pendingMessages.delete(commandId)
-            this.acceptanceWaiters.get(parsed.data.command_uuid)?.reject(new AgentDeliveryUnknownError({
-                message: `Claude command ended as ${parsed.data.state} before acceptance was observed.`,
+            const compaction = this.compactionWaiter
+            if (compaction?.clientMessageId === frame.command_uuid) {
+                this.settleCompaction(compaction, {
+                    status: 'failed',
+                    error: { message: 'Claude refused context compaction.' },
+                })
+                waiter?.resolve()
+                return
+            }
+            if (frame.state === 'refused') {
+                this.eventMapperState.promptCommandByInputId.delete(frame.command_uuid)
+                waiter?.reject(new AgentNotAcceptedError({
+                    message: 'Claude declined the input before queueing it; it will not run in this session.',
+                    recovery: { kind: 'terminal', reason: 'provider_refused' },
+                }))
+                return
+            }
+            // A cancelled (steered-over or aborted) or discarded input will not be accepted; the
+            // waiter settles now so command processing can advance while the session stays open.
+            waiter?.reject(new AgentDeliveryUnknownError({
+                message: `Claude command ended as ${frame.state} before acceptance was observed.`,
             }))
-            this.commandByClientMessageId.delete(parsed.data.command_uuid)
-            if (!this.hasPendingSteer())
-                this.flushSteerResult()
-            return
-        }
-        // A queued receipt acknowledges admission, not turn ownership. Keep the
-        // mapping after acceptance settles: the provider's started receipt is
-        // the authority for the next root turn, even with several queued inputs.
-        if (parsed.data.state === 'started') {
-            const pending = commandId ? this.pendingMessages.get(commandId) : undefined
-            // Only a native started receipt can join the interrupted segment to a steer.
-            // A queued receipt alone must never suppress the logical turn's completion.
-            this.flushSteerResult(pending?.mode === 'steer' && (!pending.turnId || pending.turnId === this.eventMapperState.currentTurnId))
+            return
+        }
+        // A queued receipt acknowledges admission, not turn ownership: the started receipt binds the
+        // command to the turn that consumes it, even with several queued inputs.
+        if (frame.state === 'started' && commandId) {
             this.eventMapperState.currentCommandId = commandId
-            if (pending && commandId) {
+            const pending = this.pendingMessages.get(commandId)
+            if (pending) {
                 pending.started = true
                 const turnId = this.eventMapperState.currentTurnId
                 if (pending.mode === 'steer' && turnId && (!pending.turnId || pending.turnId === turnId))
                     this.emitAcceptedMessage(commandId, turnId)
             }
         }
-        if (parsed.data.state === 'completed') {
-            this.commandByClientMessageId.delete(parsed.data.command_uuid)
+        if (frame.state === 'completed') {
+            this.commandByClientMessageId.delete(frame.command_uuid)
             if (commandId)
                 this.pendingMessages.delete(commandId)
         }
-        this.acceptanceWaiters.get(parsed.data.command_uuid)?.resolve()
+        waiter?.resolve()
+    }
+
+    // An accepted compaction runs as the next main turn, since it is submitted only while idle. If that
+    // turn ends without a correlated outcome, the compaction is over: report `unknown` if nothing was
+    // reported yet and stop deferring steers.
+    private endCompactionWithItsTurn(drafts: AgentEventDraft[]): void {
+        const waiter = this.compactionWaiter
+        if (waiter?.accepted && drafts.some(draft => draft.type === 'turn.ended' && draft.actor.type === 'main'))
+            this.endCompaction(waiter, { status: 'unknown' })
+    }
+
+    private observeCompactionResult(message: SDKMessage): void {
+        const waiter = this.compactionWaiter
+        if (!waiter)
+            return
+        if (message.type === 'system' && message.subtype === 'compact_boundary') {
+            if (message.compact_metadata.trigger === 'manual')
+                waiter.boundaryObserved = true
+            return
+        }
+        if (message.type === 'system' && message.subtype === 'status' && message.compact_result === 'failed') {
+            this.settleCompaction(waiter, {
+                status: 'failed',
+                error: compactionError(message),
+            })
+            return
+        }
+        if (message.type !== 'result')
+            return
+        const commandIds = resultUserMessageIds(message)
+        if (!commandIds.includes(waiter.clientMessageId))
+            return
+        if (message.subtype !== 'success' || message.is_error) {
+            this.settleCompaction(waiter, {
+                status: 'failed',
+                error: resultError(message),
+            })
+            return
+        }
+        if (waiter.boundaryObserved) {
+            this.settleCompaction(waiter, { status: 'completed' })
+            return
+        }
+        this.settleCompaction(waiter, {
+            status: 'no_op',
+            reason: message.result,
+        })
     }
 
     // Exactly one message may enter the stream before init: the first input wakes the CLI and then
@@ -482,31 +1166,31 @@ export class ClaudeRun implements AgentRun {
                 // 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)
+                    const interrupt = this.eventMapperState.interrupt
+                    await this.emitDrafts(this.settleAcceptance(message), interrupt)
                     continue
                 }
-                if (!this.initialized) {
-                    this.completeInitialization(message)
+                // A skill reload can precede the first input, so the command list is routed to the
+                // catalog before the PRE_INIT barrier; it is catalog input, not a session event.
+                if (message.type === 'system' && message.subtype === 'commands_changed') {
+                    this.skillCatalog.publish(message.commands)
                     continue
                 }
-                this.flushSteerResult()
-                if (message.type === 'result' && this.hasPendingSteer()) {
-                    // priority: now ends the current segment and yields its result before the
-                    // cancelled/started receipts: a success after a tool call or mid-response
-                    // (null stop reason), or error_during_execution when the CLI aborted the
-                    // in-flight model call (the steer landed while the model was still thinking).
-                    // Hold it until that native boundary proves continuation of the logical turn
-                    // or its true completion; a steer must never open a new turn.
-                    this.pendingSteerResult = message
+                if (!this.initialized) {
+                    if (isClaudePreInitHookMessage(message)) {
+                        this.admitPreInitializationHook(message)
+                        continue
+                    }
+                    if (message.type === 'system' && message.subtype === 'session_state_changed') {
+                        this.admitPreInitializationSessionState(message)
+                        continue
+                    }
+                    this.completeInitialization(message)
+                    for (const held of this.preInitSessionStates.splice(0))
+                        await this.mapMessage(held)
                     continue
                 }
-                const completeMessage = message.type === 'user'
-                    ? await hydrateClaudeToolOutput(message, {
-                            transcriptPath: this.metadata.transcriptPath,
-                            toolNameById: this.eventMapperState.toolNameById,
-                        })
-                    : message
-                for (const draft of mapClaudeMessage(completeMessage, this.eventMapperState)) this.pushEvent(draft)
+                await this.mapMessage(message)
             }
             // An intentional stop already finalized the run; the ended stream is expected then.
             if (this.finished)
@@ -514,7 +1198,13 @@ export class ClaudeRun implements AgentRun {
             if (!this.initialized) {
                 throw new AgentProviderProtocolError({ message: 'Claude SDK ended before emitting system init.' })
             }
-            this.flushSteerResult()
+            // A superseded ask's held end is final once the stream can deliver no steer to continue it.
+            await this.emitDrafts(flushHeldTurnEnd(this.eventMapperState), this.eventMapperState.interrupt)
+            // The SDK reports non-zero exits and signals as errors, but a clean exit mid-turn ends the stream
+            // without a result: that turn did not complete.
+            if (this.eventMapperState.currentTurnId) {
+                throw new AgentProviderProtocolError({ message: 'Claude SDK ended before the active turn reported its result.' })
+            }
             this.finish('completed')
         }
         catch (error) {
@@ -525,9 +1215,58 @@ export class ClaudeRun implements AgentRun {
         }
     }
 
+    private async mapMessage(message: SDKMessage): Promise<void> {
+        const completeMessage = this.hydratePersistedToolOutput && message.type === 'user'
+            ? await hydrateClaudeToolOutput(message, {
+                    transcriptPath: this.metadata.transcriptPath,
+                    toolNameById: this.eventMapperState.toolNameById,
+                })
+            : message
+        // The mapper resets the interrupt when it ends the turn; the follow-up needs it.
+        const interrupt = this.eventMapperState.interrupt
+        const drafts = mapClaudeMessage(completeMessage, this.eventMapperState)
+        for (const draft of drafts) this.pushEvent(draft)
+        // A compaction's request result follows the lifecycle events of the message that settles it.
+        this.observeCompactionResult(message)
+        this.endCompactionWithItsTurn(drafts)
+        await this.followUpCompletedTurn(drafts, interrupt)
+    }
+
+    private async emitDrafts(drafts: AgentEventDraft[], interrupt: ClaudeEventMapperState['interrupt']): Promise<void> {
+        for (const draft of drafts) this.pushEvent(draft)
+        await this.followUpCompletedTurn(drafts, interrupt)
+    }
+
+    private async followUpCompletedTurn(drafts: AgentEventDraft[], interrupt: ClaudeEventMapperState['interrupt']): Promise<void> {
+        if (drafts.some(draft => draft.type === 'turn.ended' && draft.actor.type === 'main' && draft.payload.status === 'completed' && !interruptTargetsTurn(interrupt, draft.turnId)))
+            await this.startSteeredNotificationFollowUp()
+    }
+
+    private admitPreInitializationSessionState(message: Extract<SDKMessage, { type: 'system', subtype: 'session_state_changed' }>): void {
+        if (message.session_id !== this.init.expectedSessionId) {
+            throw new AgentProviderProtocolError({
+                message: 'Claude SDK pre-init session state session_id does not match the requested session.',
+                details: { expected: this.init.expectedSessionId, actual: message.session_id },
+            })
+        }
+        this.preInitSessionStates.push(message)
+    }
+
+    private admitPreInitializationHook(message: ClaudePreInitHookMessage): void {
+        if (message.session_id !== this.init.expectedSessionId) {
+            throw new AgentProviderProtocolError({
+                message: 'Claude SDK pre-init hook session_id does not match the requested session.',
+                details: { expected: this.init.expectedSessionId, actual: message.session_id },
+            })
+        }
+    }
+
     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.' })
+            throw new AgentProviderProtocolError({
+                message: 'Claude SDK emitted an unexpected message before system init.',
+                details: { type: message.type, subtype: 'subtype' in message ? message.subtype : undefined },
+            })
         }
         const init: ClaudeInitMessage = message
         if (!init.session_id) {
@@ -539,7 +1278,7 @@ export class ClaudeRun implements AgentRun {
                 details: { expected: this.init.expectedSessionId, actual: init.session_id },
             })
         }
-        const effectiveModel = init.model ?? this.init.requestedModel
+        const effectiveModel = init.model ?? this.current.model
         if (!effectiveModel) {
             throw new AgentProviderMetadataError({ message: 'Claude SDK init did not include model.', details: { provider: 'claude' } })
         }
@@ -549,25 +1288,26 @@ export class ClaudeRun implements AgentRun {
         this.pushEvent(sessionConfiguredEvent({
             model: effectiveModel,
             cwd: init.cwd ?? this.metadata.cwd,
-            reasoningEffort: this.init.reasoningEffort,
+            reasoningEffort: this.current.effort,
             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.skillCatalog.markReady()
         this.recordStartup?.('session_ready')
-        this.initializationResolve()
+        this.initializationResolve(effectiveModel)
     }
 
     private failRun(error: unknown): void {
         if (this.finished)
             return
-        const agentError = serializeAgentError(error)
+        const agentError = withProcessStderr(serializeAgentError(error), this.process.stderrTail())
         if (!this.initialized) {
             // Pre-init failure: the first-input promise must reject typed instead of hanging.
             this.initializationReject(error)
-            this.query.close()
+            this.closeQuery()
             this.finish('failed', agentError)
             return
         }
@@ -575,6 +1315,14 @@ export class ClaudeRun implements AgentRun {
         this.finish('failed', agentError)
     }
 
+    // Query.close() ends the CLI's stdin; every ending path and the final exit wait share one call.
+    private closeQuery(): void {
+        if (this.queryClosed)
+            return
+        this.queryClosed = true
+        this.query.close()
+    }
+
     private assertRunning(): void {
         if (this.finished)
             throw new AgentRunStateError({ message: 'Claude run has stopped.' })
@@ -586,3 +1334,18 @@ export class ClaudeRun implements AgentRun {
         }
     }
 }
+
+// The SDK appends the CLI's stderr tail to its process-exit errors only for its own spawn; the run
+// spawns the CLI itself (claude-code-process.ts), so it restores that diagnostic here.
+function withProcessStderr(error: AgentError, stderrTail: string): AgentError {
+    if (!stderrTail || !/^Claude Code process (?:exited with code|terminated by signal) \S+$/u.test(error.message))
+        return error
+    return { ...error, message: `${error.message}. stderr: ${stderrTail}` }
+}
+
+// SDK 0.3.280 reports every input a result consumed; older pinned runtimes report only one.
+function resultUserMessageIds(message: Extract<SDKMessage, { type: 'result' }>): readonly string[] {
+    if ('user_message_uuids' in message && Array.isArray(message.user_message_uuids))
+        return message.user_message_uuids.filter((id): id is string => typeof id === 'string')
+    return message.user_message_uuid ? [message.user_message_uuid] : []
+}