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

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

@@ -1,49 +1,85 @@
 import type {
     AgentAuthor,
+    AgentContextCompactionRequestResult,
+    AgentNotifyCommand,
     AgentPrompt,
     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 { AgentSettingsPlacement } from '../agent-session-events'
 import type { UserInputRequestInput, UserInputRequestStore } from '../user-input-request'
 import type { CodexEventMapperState } from './codex-event-mapper'
 import type { CodexJsonRpcClient } from './codex-json-rpc-client'
-import type { ClientRequestResponsesByMethod, CodexTurnStartParams, CodexUserInput } from './codex-protocol'
+import type { ClientRequestResponsesByMethod, CodexUserInput } from './codex-protocol'
+import { serializeAgentNotificationToolOutput } from '../../protocol'
 import { AgentEventStream } from '../agent-event-stream'
 import { AgentDeliveryUnknownError, AgentNotAcceptedError, AgentPromptDeferredError, AgentRunStateError } from '../agent-runtime-error'
+import { sessionSettingsChangedEvent } from '../agent-session-events'
 import { deriveMessageId } from '../message-id'
-import { codexEffort, prepareCodexUserInput, toCodexUserInput } from './codex-command-mapper'
+import { codexEffort, codexReasoningSummary, prepareCodexUserInput, toCodexUserInput } from './codex-command-mapper'
 import { CodexJsonRpcResponseError } from './codex-json-rpc-client'
 import { CodexSkillCatalog } from './codex-skill-catalog'
 import { catalogRepositorySkillRoots, workspaceSkillRoots } from './codex-skill-roots'
 import { CodexJsonRpcTransportClosedError } from './codex.errors'
 
-const codexReasoningSummary: CodexTurnStartParams['summary'] = 'auto'
+const codexNotificationTurnTrigger = 'application_notification'
+const codexNotificationToolNamespace = 'coding_agent'
+const codexNotificationToolName = 'session_notifications'
 
 interface CodexRunAuthFailureInput {
     reason: 'codex_auth_refresh_failed'
     error: { message: string, name?: string, stack?: string }
 }
 
-interface PreparedCodexTurn {
+interface PreparedCodexPromptTurn {
     input: CodexUserInput[]
     commandId: string
     origin: 'user' | 'supervisor'
-    model?: string
-    reasoningEffort?: AgentReasoningEffort
+    sessionContext: string | undefined
+}
+
+// The model and effort the run sends with every turn/start. Codex applies turn/start settings to that
+// turn and every later one, so each turn must carry the current values or it silently reverts a change.
+interface CodexTurnSettings {
+    model: string
+    effort: AgentReasoningEffort | undefined
+}
+
+interface PreparedCodexTurnStart {
+    commandId: string
+    settings: CodexTurnSettings
+    content:
+        | { kind: 'prompt', input: CodexUserInput[], origin: 'user' | 'supervisor' }
+        | { kind: 'notification', output: string }
+}
+
+interface CodexTurnStartReceipt {
+    kind: 'turn'
+    turnId: string
+}
+
+interface CodexTurnStartResult {
+    receipt: CodexTurnStartReceipt
+    placement: 'started' | 'steered'
 }
 
 interface CodexRunInput {
     beforePrompt?: (signal?: AbortSignal) => Promise<void>
     resolveInferenceModel?: (model: string) => string
     metadata: AgentRunMetadata
-    reasoningEffort?: AgentReasoningEffort
+    // Delivered once, with the session's first prompt, then cleared (see session-context.ts).
+    sessionContext: string | undefined
+    // The resolved settings the thread was opened or resumed with.
+    settings: CodexTurnSettings
     client: CodexJsonRpcClient
     requestedCwd: string
     workspaceRepositoryRoots: readonly string[]
@@ -53,7 +89,7 @@ interface CodexRunInput {
     userInputRequests: UserInputRequestStore
     eventMapperState: CodexEventMapperState
     abortSignal: AbortSignal
-    onStop: () => void
+    onStop: () => void | Promise<void>
 }
 
 export class CodexRun implements AgentRun {
@@ -62,8 +98,8 @@ export class CodexRun implements AgentRun {
     private readonly client: CodexJsonRpcClient
     private readonly beforePrompt: ((signal?: AbortSignal) => Promise<void>) | undefined
     private readonly resolveInferenceModel: (model: string) => string
-    private reasoningEffort: AgentReasoningEffort | undefined
-    private readonly onStop: () => void
+    private current: CodexTurnSettings
+    private readonly onStop: () => void | Promise<void>
     private readonly userInputRequests: UserInputRequestStore
     private readonly eventMapperState: CodexEventMapperState
     private readonly skillCatalog: CodexSkillCatalog
@@ -75,14 +111,16 @@ export class CodexRun implements AgentRun {
     private stopped = false
     private stoppingTask: Promise<void> | undefined
     private activeTurnId: string | undefined
+    private sessionContext: string | undefined
     private readonly interruptingTurnIds = new Set<string>()
 
     constructor(input: CodexRunInput) {
         this.metadata = input.metadata
+        this.sessionContext = input.sessionContext
         this.client = input.client
         this.beforePrompt = input.beforePrompt
         this.resolveInferenceModel = input.resolveInferenceModel ?? (model => model)
-        this.reasoningEffort = input.reasoningEffort
+        this.current = { ...input.settings }
         this.onStop = input.onStop
         this.userInputRequests = input.userInputRequests
         this.eventMapperState = input.eventMapperState
@@ -205,6 +243,10 @@ export class CodexRun implements AgentRun {
     }
 
     async failActiveTurnAndEndRun(input: CodexRunAuthFailureInput): Promise<void> {
+        if (this.stoppingTask) {
+            await this.stoppingTask
+            return
+        }
         if (this.stopped)
             return
         this.pushEvent({ type: 'error', payload: { message: 'Codex auth refresh failed.', fatal: false, source: 'provider', error: input.error } })
@@ -220,23 +262,38 @@ export class CodexRun implements AgentRun {
         }
         this.pushEvent({ type: 'session.state.changed', payload: { state: 'failed' } })
         this.stopped = true
-        // Pinned Codex forwards preceding stdin lines before EOF, preserving the refresh error ordering.
-        await this.client.closeInputAndStop()
-        this.events.push({ type: 'session.ended', payload: { reason: 'failed', error: input.error } })
-        this.events.end()
+        // The refresh error was flushed before this path. Revoke run capabilities while
+        // native EOF/signal escalation proceeds, not after a potentially slow child exit.
+        const stopping = Promise.withResolvers<void>()
+        this.stoppingTask = stopping.promise
+        this.startStopping(() => {
+            this.events.push({ type: 'session.ended', payload: { reason: 'failed', error: input.error } })
+            this.events.end()
+        }, stopping)
+        await stopping.promise
     }
 
-    async sendPrompt(command: SendPromptCommand, options: AgentOperationOptions = {}): Promise<AgentPromptAcceptance> {
+    async sendPrompt(command: SendPromptCommand, options: AgentPromptOperationOptions = {}): Promise<AgentPromptAcceptance> {
         this.assertCommandTargetsRun(command)
         this.assertRunning()
+        options.signal?.throwIfAborted()
+        this.assertSubmissionOrder(command.mode, options.submissionOrder)
         // Released 0.145.0 accepts turn/start during an active turn by silently steering the input
-        // and answering a phantom turn id, so the next-vs-active race must be refused from adapter
-        // state before any request — nothing is prepared or retained.
-        this.deferNextWhileTurnActive(command.mode)
-        if (this.beforePrompt)
+        // and answering a phantom turn id, so in-order next-vs-active races are refused before any
+        // request. Bypass submission instead requires an active turn before preparation.
+        const submissionOrder = options.submissionOrder ?? 'in-order'
+        if (submissionOrder === 'in-order')
+            this.deferNextWhileTurnActive(command.mode)
+        else
+            this.deferBypassWithoutTurn()
+        if (this.beforePrompt) {
             await this.beforePrompt(options.signal)
-        this.assertRunning()
-        this.deferNextWhileTurnActive(command.mode)
+            this.assertRunning()
+            if (submissionOrder === 'in-order')
+                this.deferNextWhileTurnActive(command.mode)
+            else
+                this.deferBypassWithoutTurn()
+        }
         const prepared = await this.prepareTurn({
             prompt: command.prompt,
             commandId: command.commandId,
@@ -244,24 +301,49 @@ export class CodexRun implements AgentRun {
             author: command.author,
             options,
         })
-        prepared.model = command.model
-        prepared.reasoningEffort = command.reasoningEffort
-        // A turn/started fact may have reduced during attachment preparation.
-        this.deferNextWhileTurnActive(command.mode)
+        // Provider events and stop can reduce while attachment preparation is awaited. Recheck the
+        // run and use the execution-time active turn before creating correlation or provider input.
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        if (submissionOrder === 'in-order')
+            this.deferNextWhileTurnActive(command.mode)
+        else
+            this.deferBypassWithoutTurn()
 
         if (command.turnId && (command.mode !== 'steer' || command.turnId !== this.activeTurnId))
             throw new AgentNotAcceptedError({ message: 'The targeted codex turn is no longer active.', recovery: { kind: 'terminal', reason: 'target_turn_not_active' } })
         const activeTurnId = this.activeTurnId
         if (activeTurnId && command.model && command.model !== this.metadata.model)
             throw new AgentPromptDeferredError({ message: 'Codex model changes require an idle turn boundary.' })
-        if (activeTurnId && command.reasoningEffort && command.reasoningEffort !== this.reasoningEffort)
+        if (activeTurnId && command.reasoningEffort && command.reasoningEffort !== this.current.effort)
             throw new AgentPromptDeferredError({ message: 'Codex reasoning effort changes require an idle turn boundary.' })
-        if (command.mode === 'next' || !activeTurnId)
-            return await this.startPreparedTurn(prepared)
+        if (command.mode === 'next' || !activeTurnId) {
+            const settings = withSettingsChange(this.current, command.settings ?? { model: command.model, reasoningEffort: command.reasoningEffort })
+            const { receipt } = await this.startTurn({
+                commandId: prepared.commandId,
+                settings,
+                content: { kind: 'prompt', input: prepared.input, origin: prepared.origin },
+            }, options)
+            this.sessionContextDelivered(prepared.sessionContext)
+            // The turn this prompt started runs on the merged settings from its first request.
+            if (command.settings)
+                this.settingsAccepted({ settings, commandId: command.commandId, turnId: receipt.turnId, placement: { appliesFrom: 'current_turn' } })
+            return { ...receipt, placement: 'started' }
+        }
 
-        const clientUserMessageId = this.rememberPromptCommand(prepared.commandId, prepared.origin)
+        // Settings must reach the provider before the input. Keep the committed settings until
+        // acceptance and compensate a proven rejection before returning the prompt to the caller.
+        const previousSettings = this.current
+        const settings = command.settings && withSettingsChange(previousSettings, command.settings)
+        const placement = settings && await this.applySteerSettings({ turnId: activeTurnId, settings })
+        const clientUserMessageId = deriveMessageId(prepared.commandId)
+        let steerRequested = false
         let result: ClientRequestResponsesByMethod['turn/steer']
         try {
+            this.assertRunning()
+            options.signal?.throwIfAborted()
+            this.rememberPromptCommand(prepared.commandId, prepared.origin)
+            steerRequested = true
             result = await this.client.request('turn/steer', {
                 threadId: this.metadata.providerSessionId,
                 expectedTurnId: activeTurnId,
@@ -270,13 +352,32 @@ export class CodexRun implements AgentRun {
             })
         }
         catch (error) {
+            const mapped = mapTurnTransportLoss(error)
+            // A lost response may represent accepted input; leave its settings intact and retain
+            // delivery-unknown recovery. Cancellation before writing and explicit refusal are safe
+            // to compensate, without using the cancelled operation's signal.
+            if (settings && placement && (!steerRequested || isSteerNotAcceptedResponse(error) || mapped instanceof AgentNotAcceptedError))
+                await this.restoreSteerSettings({ turnId: activeTurnId, previousSettings, settings, placement })
             if (isSteerNotAcceptedResponse(error)) {
+                if (submissionOrder === 'bypass')
+                    this.eventMapperState.promptCommandByClientUserMessageId.delete(clientUserMessageId)
                 throw new AgentPromptDeferredError({
                     message: 'Codex rejected the steer at a turn boundary race.',
                     cause: error,
                 })
             }
-            throw mapTurnTransportLoss(error)
+            if (submissionOrder === 'bypass' && mapped instanceof AgentNotAcceptedError)
+                this.eventMapperState.promptCommandByClientUserMessageId.delete(clientUserMessageId)
+            throw mapped
+        }
+        this.sessionContextDelivered(prepared.sessionContext)
+        if (settings && placement) {
+            this.settingsAccepted({
+                settings,
+                commandId: command.commandId,
+                turnId: placement.appliesFrom === 'current_turn' ? activeTurnId : undefined,
+                placement,
+            })
         }
         return { kind: 'turn', turnId: result.turnId, placement: 'steered' }
     }
@@ -285,6 +386,97 @@ export class CodexRun implements AgentRun {
         return this.activeTurnId !== undefined
     }
 
+    // Changes the running turn (only honoured with `features.step_model_switching`) and the thread's
+    // later turns. Sends only the fields that differ from `current`; with none, no provider call and the
+    // running turn already runs on those values.
+    private async applySteerSettings({ turnId, settings }: { turnId: string, settings: CodexTurnSettings }): Promise<AgentSettingsPlacement> {
+        const changes = {
+            ...(settings.model === this.current.model ? {} : { model: this.resolveInferenceModel(settings.model) }),
+            ...(settings.effort === this.current.effort ? {} : { effort: codexEffort(settings.effort) }),
+        }
+        if (Object.keys(changes).length === 0)
+            return { appliesFrom: 'current_turn' }
+
+        const threadId = this.metadata.providerSessionId
+        // Least durable effect first: thread defaults only reach future turns, and every turn/start
+        // re-sends the committed `current`, so a failure after this call leaves nothing that outlives
+        // the next turn. The running turn changes last, so a failed thread update never leaves the
+        // active turn on settings the steer was not accepted for.
+        try {
+            await this.client.request('thread/settings/update', { threadId, ...changes })
+        }
+        catch (error) {
+            throw mapSettingsTransportLoss(error)
+        }
+        try {
+            const result = await this.client.request('turn/settings/update', { threadId, turnId, ...changes })
+            // `targetUnavailable` (the turn ended or was replaced first) carries no provider reason.
+            return result.status === 'applied' ? { appliesFrom: 'current_turn' } : { appliesFrom: 'next_turn' }
+        }
+        catch (error) {
+            if (!isTurnSettingsUnavailableResponse(error))
+                throw mapSettingsTransportLoss(error)
+            return { appliesFrom: 'next_turn', currentTurnUnavailableReason: error.responseErrorMessage || undefined }
+        }
+    }
+
+    private async restoreSteerSettings(input: { turnId: string, previousSettings: CodexTurnSettings, settings: CodexTurnSettings, placement: AgentSettingsPlacement }): Promise<void> {
+        const { turnId, previousSettings, settings, placement } = input
+        const modelChanged = settings.model !== previousSettings.model
+        const effortChanged = settings.effort !== previousSettings.effort
+        if (!modelChanged && !effortChanged)
+            return
+        const threadId = this.metadata.providerSessionId
+        try {
+            // The SDK treats null/omitted effort as unchanged. An implicit provider default cannot
+            // be reconstructed here, so retire this run instead of claiming it was restored.
+            if (effortChanged && previousSettings.effort === undefined)
+                throw new AgentRunStateError({ message: 'Cannot restore an implicit Codex reasoning effort.' })
+            const changes = {
+                ...(modelChanged ? { model: this.resolveInferenceModel(previousSettings.model) } : {}),
+                ...(effortChanged ? { effort: codexEffort(previousSettings.effort) } : {}),
+            }
+            // Restore the active turn first. targetUnavailable is safe: that turn can no longer
+            // execute with the tentative settings. A refusal/transport failure is not restoration.
+            if (placement.appliesFrom === 'current_turn')
+                await this.client.request('turn/settings/update', { threadId, turnId, ...changes })
+            await this.client.request('thread/settings/update', { threadId, ...changes })
+        }
+        catch (error) {
+            // Do not defer while an active provider can continue on unaccepted settings.
+            await this.stop({ type: 'agent.stop', provider: 'codex', sessionId: this.metadata.sessionId, providerSessionId: threadId, reason: 'settings-rollback-failed' })
+            throw new AgentNotAcceptedError({
+                message: 'Codex settings could not be restored after a rejected steer; the run was stopped.',
+                recovery: { kind: 'retry', reason: 'provider_connection_lost' },
+                cause: error,
+            })
+        }
+    }
+
+    private settingsAccepted(input: { settings: CodexTurnSettings, commandId: string, turnId: string | undefined, placement: AgentSettingsPlacement }): void {
+        this.current = input.settings
+        this.pushEvent(sessionSettingsChangedEvent({
+            model: input.settings.model,
+            reasoningEffort: input.settings.effort,
+            commandId: input.commandId,
+            turnId: input.turnId,
+            ...input.placement,
+        }))
+    }
+
+    private sessionContextDelivered(sessionContext: string | undefined): void {
+        if (sessionContext !== undefined && this.sessionContext === sessionContext)
+            this.sessionContext = undefined
+    }
+
+    private assertSubmissionOrder(mode: SendPromptCommand['mode'], submissionOrder: AgentPromptOperationOptions['submissionOrder']): void {
+        if (submissionOrder === 'bypass' && mode === 'next') {
+            throw new AgentRunStateError({
+                message: 'Bypass submission requires a steer prompt.',
+            })
+        }
+    }
+
     private deferNextWhileTurnActive(mode: SendPromptCommand['mode']): void {
         if (mode !== 'next' || !this.activeTurnId)
             return
@@ -293,6 +485,93 @@ export class CodexRun implements AgentRun {
         })
     }
 
+    private deferBypassWithoutTurn(): void {
+        if (this.activeTurnId)
+            return
+        throw new AgentPromptDeferredError({
+            message: 'Codex has no active turn for bypass prompt submission.',
+        })
+    }
+
+    async notify(command: AgentNotifyCommand, options: AgentOperationOptions = {}): Promise<AgentNotificationAcceptance> {
+        this.assertCommandTargetsRun(command)
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        this.deferNotificationForUnresolvedUserInput()
+
+        const { receipt, placement } = await this.startTurn({
+            commandId: command.commandId,
+            settings: this.current,
+            content: {
+                kind: 'notification',
+                output: serializeAgentNotificationToolOutput({
+                    commandId: command.commandId,
+                    instruction: command.instruction,
+                    notifications: command.notifications,
+                }),
+            },
+        }, options)
+        return { ...receipt, placement }
+    }
+
+    private deferNotificationForUnresolvedUserInput(): void {
+        if (this.userInputRequests.hasUnresolvedUserInput()) {
+            throw new AgentPromptDeferredError({
+                message: 'Codex is waiting for unresolved user input; a notification cannot be submitted.',
+            })
+        }
+    }
+
+    async compactContext(command: CompactContextAgentCommand, options: AgentOperationOptions = {}): Promise<AgentContextCompactionRequestResult> {
+        this.assertCommandTargetsRun(command)
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        if (this.activeTurnId) {
+            throw new AgentPromptDeferredError({
+                message: 'Codex turn is active; context compaction must wait for an idle main thread.',
+            })
+        }
+
+        let result: AgentContextCompactionRequestResult
+        try {
+            await this.client.request('thread/compact/start', { threadId: this.metadata.providerSessionId })
+            // The pinned RPC response is an empty acknowledgement. Native item/turn lifecycle has
+            // no request identity or manual/auto discriminator, so this control result stays unknown.
+            result = { status: 'unknown' }
+        }
+        catch (error) {
+            if (error instanceof CodexJsonRpcTransportClosedError) {
+                if (error.writeState === 'possible_write') {
+                    result = { status: 'unknown' }
+                }
+                else {
+                    throw new AgentNotAcceptedError({
+                        message: 'Codex app-server connection closed before the compact request was written.',
+                        recovery: { kind: 'retry', reason: 'provider_connection_lost' },
+                        cause: error,
+                    })
+                }
+            }
+            else if (error instanceof CodexJsonRpcResponseError) {
+                result = {
+                    status: 'failed',
+                    error: {
+                        message: error.responseErrorMessage || 'Codex rejected context compaction.',
+                        ...(error.responseErrorCode === undefined ? {} : { code: String(error.responseErrorCode) }),
+                    },
+                }
+            }
+            else {
+                throw error
+            }
+        }
+        this.pushEvent({
+            type: 'context.compaction.request.completed',
+            payload: { commandId: command.commandId, result },
+        })
+        return result
+    }
+
     async respondUserInput(command: RespondUserInputAgentCommand, options: AgentOperationOptions = {}): Promise<AgentUserInputSubmission> {
         this.assertCommandTargetsRun(command)
         this.assertRunning()
@@ -303,7 +582,12 @@ export class CodexRun implements AgentRun {
         if (resolved.event)
             this.pushEvent(resolved.event)
         const prepared = await this.prepareTurn({ prompt: resolved.prompt, commandId: command.commandId, options })
-        await this.startPreparedTurn(prepared)
+        await this.startTurn({
+            commandId: prepared.commandId,
+            settings: this.current,
+            content: { kind: 'prompt', input: prepared.input, origin: prepared.origin },
+        }, options)
+        this.sessionContextDelivered(prepared.sessionContext)
         this.userInputRequests.markDelivered(command.requestId)
         return 'submitted'
     }
@@ -341,53 +625,100 @@ export class CodexRun implements AgentRun {
         options.signal?.throwIfAborted()
         this.stopped = true
         this.events.push({ type: 'session.state.changed', payload: { state: 'stopping' } })
-        this.onStop()
-        this.stoppingTask = (async () => {
-            await this.client.stop()
+        const stopping = Promise.withResolvers<void>()
+        this.stoppingTask = stopping.promise
+        this.startStopping(() => {
             this.events.push({ type: 'session.ended', payload: { reason: 'stopped' } })
             this.events.push({ type: 'session.state.changed', payload: { state: 'stopped' } })
             this.events.end()
-        })()
-        await this.stoppingTask
+        }, stopping)
+        await stopping.promise
     }
 
-    private async prepareTurn({ prompt, commandId, origin = 'user', author, options }: { prompt: AgentPrompt, commandId: string, origin?: 'user' | 'supervisor', author?: AgentAuthor, options: AgentOperationOptions }): Promise<PreparedCodexTurn> {
+    private startStopping(finalize: () => void, stopping: PromiseWithResolvers<void>): void {
+        const revocation = new Promise<void>((resolve) => {
+            resolve(this.onStop())
+        })
+        void Promise.all([this.client.stop(), revocation])
+            .then(finalize)
+            .then(stopping.resolve, stopping.reject)
+    }
+
+    private async prepareTurn({ prompt, commandId, origin = 'user', author, options }: { prompt: AgentPrompt, commandId: string, origin?: 'user' | 'supervisor', author?: AgentAuthor, options: AgentOperationOptions }): Promise<PreparedCodexPromptTurn> {
         options.signal?.throwIfAborted()
-        const mapperInput = { prompt, origin, author, senderContext: options.senderContext }
+        const sessionContext = this.sessionContext
+        const mapperInput = { prompt, origin, author, senderContext: options.senderContext, authorContext: options.authorContext, sessionContext }
         const input = options.inputAttachmentPreparation
             ? await prepareCodexUserInput({ ...mapperInput, preparation: options.inputAttachmentPreparation })
             : toCodexUserInput(mapperInput)
         options.signal?.throwIfAborted()
-        return { input, commandId, origin }
+        return { input, commandId, origin, sessionContext }
     }
 
-    private async startPreparedTurn(prepared: PreparedCodexTurn): Promise<AgentPromptAcceptance> {
-        const publicModel = prepared.model ?? this.metadata.model
+    private async startTurn(prepared: PreparedCodexTurnStart, options: AgentOperationOptions): Promise<CodexTurnStartResult> {
+        // Provider state can change during prompt preparation or notification serialization. Keep
+        // the last no-write guard and abort check at the shared turn/start boundary.
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        if (prepared.content.kind === 'notification')
+            this.deferNotificationForUnresolvedUserInput()
+        else if (this.activeTurnId)
+            this.deferNextWhileTurnActive('next')
+        const activeTurnIdAtSubmission = this.activeTurnId
+        const publicModel = prepared.settings.model
         const inferenceModel = publicModel ? this.resolveInferenceModel(publicModel) : undefined
-        const clientUserMessageId = this.rememberPromptCommand(prepared.commandId, prepared.origin)
+
+        const clientUserMessageId = prepared.content.kind === 'prompt'
+            ? this.rememberPromptCommand(prepared.commandId, prepared.content.origin)
+            : deriveMessageId(prepared.commandId)
+        const notificationParams = prepared.content.kind === 'notification'
+            ? {
+                    turnTrigger: codexNotificationTurnTrigger,
+                    toolOutput: {
+                        namespace: codexNotificationToolNamespace,
+                        name: codexNotificationToolName,
+                        output: prepared.content.output,
+                    },
+                }
+            : {}
+
         let result: ClientRequestResponsesByMethod['turn/start']
         try {
             result = await this.client.request('turn/start', {
                 threadId: this.metadata.providerSessionId,
-                input: prepared.input,
+                input: prepared.content.kind === 'prompt' ? prepared.content.input : [],
                 cwd: this.metadata.cwd,
                 model: inferenceModel,
-                effort: codexEffort(prepared.reasoningEffort ?? this.reasoningEffort),
+                effort: codexEffort(prepared.settings.effort),
                 summary: codexReasoningSummary,
                 approvalPolicy: 'never',
                 sandboxPolicy: { type: 'dangerFullAccess' },
                 clientUserMessageId,
+                ...notificationParams,
             })
         }
         catch (error) {
+            if (prepared.content.kind === 'notification' && isNotificationNotAcceptedResponse(error)) {
+                throw new AgentPromptDeferredError({
+                    message: 'Codex active turn cannot accept a notification.',
+                    cause: error,
+                })
+            }
             throw mapTurnTransportLoss(error)
         }
-        this.activeTurnId = result.turn.id
-        if (prepared.reasoningEffort)
-            this.reasoningEffort = prepared.reasoningEffort
-        if (prepared.model)
-            this.metadata.model = prepared.model
-        return { kind: 'turn', turnId: result.turn.id, placement: 'started' }
+        const placement = prepared.content.kind === 'notification'
+            && activeTurnIdAtSubmission === result.turn.id
+            ? 'steered'
+            : 'started'
+        if (placement === 'started') {
+            this.activeTurnId = result.turn.id
+            this.current = prepared.settings
+            this.metadata.model = prepared.settings.model
+        }
+        return {
+            receipt: { kind: 'turn', turnId: result.turn.id },
+            placement,
+        }
     }
 
     private rememberPromptCommand(commandId: string, origin: 'user' | 'supervisor'): string {
@@ -416,6 +747,45 @@ function isSteerNotAcceptedResponse(error: unknown): error is CodexJsonRpcRespon
     return error instanceof CodexJsonRpcResponseError && error.method === 'turn/steer' && error.responseErrorCode === -32600
 }
 
+function withSettingsChange(current: CodexTurnSettings, change: AgentSettingsChange | undefined): CodexTurnSettings {
+    return {
+        model: change?.model ?? current.model,
+        effort: change?.reasoningEffort ?? current.effort,
+    }
+}
+
+// A running turn that cannot take new settings is not a failure: they apply from the next turn.
+// Pinned Codex answers -32600 with its reason as the message when `features.step_model_switching` is off
+// (live-verified on 0.153.4) or when its legacy turn-safety check refuses the destination model
+// (core/src/session/step_activation.rs at rust-v0.156.1, live-verified for gpt-6-astra -> gpt-5.5).
+function isTurnSettingsUnavailableResponse(error: unknown): error is CodexJsonRpcResponseError {
+    return error instanceof CodexJsonRpcResponseError && error.method === 'turn/settings/update' && error.responseErrorCode === -32600
+}
+
+// Settings requests run before the prompt is written, so losing the connection during one proves
+// the prompt was not delivered, whatever the settings request's own write state.
+function mapSettingsTransportLoss(error: unknown): unknown {
+    if (!(error instanceof CodexJsonRpcTransportClosedError))
+        return error
+    return new AgentNotAcceptedError({
+        message: 'Codex app-server connection was lost while applying prompt settings; the prompt was not written.',
+        recovery: { kind: 'retry', reason: 'provider_connection_lost' },
+        cause: error,
+    })
+}
+
+// Pinned Codex reports a standalone tool output as definitively not submitted when the active turn is
+// review or compaction work. The app-server currently exposes that Core reason only in this exact error.
+function isNotificationNotAcceptedResponse(error: unknown): error is CodexJsonRpcResponseError {
+    if (!(error instanceof CodexJsonRpcResponseError)
+        || error.method !== 'turn/start'
+        || error.responseErrorCode !== -32603) {
+        return false
+    }
+    return error.responseErrorMessage === 'failed to submit turn input: ActiveTurnNotSteerable { turn_kind: Review }'
+        || error.responseErrorMessage === 'failed to submit turn input: ActiveTurnNotSteerable { turn_kind: Compact }'
+}
+
 // Transport loss on an input-carrying request maps to write-state truth: possible_write means the
 // input may already be in the provider thread (delivery unknown, never blind-retryable);
 // before_write is proven non-delivery and safe to retry. Anything else passes through unchanged.