@meistrari/agent-core 0.1.2 → 0.1.8

package/README.md

@@ -21,6 +21,8 @@ The package ships TypeScript source and targets Bun `>=1.3.10`. There is no wire
 
 agent-core does not own a universal E2B template. Each consuming service builds and onboards its own template against the shared contracts and records that template's agent-core provenance. agent-api and Remy may therefore use different base images, harness versions, system packages, and startup hooks without forking the control protocol.
 
+Prompt commands may carry an application-resolved `model`. Applications validate harness compatibility and persist the selection with command admission; they should send the resolved model on every prompt so recovery does not depend on mutable harness memory. Claude applies a changed model through its control channel before input; Codex supplies it to `turn/start`. Neither adapter changes models on an active turn, and unchanged Claude selections add no control request. This is not an effort override contract. Existing immutable sandboxes must not be advertised as supporting this field unless their baked runtime includes it.
+
 ## Development
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@meistrari/agent-core",
     "type": "module",
-    "version": "0.1.2",
+    "version": "0.1.8",
     "packageManager": "bun@1.3.12",
     "description": "Shared contracts and runtime modules for Tela coding-agent sandboxes: agent protocol, supervisor wire protocol, resident supervisor, worker runtime client, and Claude/Codex harness adapters.",
     "license": "UNLICENSED",

package/scripts/probe-codex-diagnostic-storage.ts

@@ -0,0 +1,110 @@
+import { spawn } from 'node:child_process'
+import { mkdtemp, readdir, readFile, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createInterface } from 'node:readline'
+import { Database } from 'bun:sqlite'
+
+// Offline, synthetic-only probe. Never inherit model or AWS credentials.
+const executable = process.argv[2]
+if (!executable)
+    throw new Error('Pass the absolute path to the pinned Codex executable.')
+
+for (const mode of ['default', 'rust-log-off', 'feedback-off'] as const) {
+    const directory = await mkdtemp(join(tmpdir(), `codex-diagnostic-${mode}-`))
+    const canary = 'SYNTHETIC_CODEX_DIAGNOSTIC_CANARY_NO_AUTHORITY'
+    const child = spawn(executable, [
+        'app-server',
+        '--listen',
+        'stdio://',
+        '-c',
+        'cli_auth_credentials_store="ephemeral"',
+        ...(mode === 'feedback-off' ? ['-c', 'feedback.enabled=false'] : []),
+    ], {
+        env: {
+            PATH: process.env.PATH,
+            HOME: directory,
+            CODEX_HOME: directory,
+            HTTP_PROXY: 'http://127.0.0.1:1',
+            HTTPS_PROXY: 'http://127.0.0.1:1',
+            ALL_PROXY: 'http://127.0.0.1:1',
+            NO_PROXY: '',
+            ...(mode === 'rust-log-off' ? { RUST_LOG: 'off' } : {}),
+        },
+        stdio: 'pipe',
+    })
+    const exited = new Promise<number | null>((resolve, reject) => {
+        child.once('close', resolve)
+        child.once('error', reject)
+    })
+    let stderrHasCanary = false
+    child.stderr.on('data', (data) => {
+        stderrHasCanary ||= String(data).includes(canary)
+    })
+    const send = (value: unknown) => child.stdin.write(`${JSON.stringify(value)}\n`)
+    let loginResponded = false
+    let turnAccepted = false
+    const protocolErrors: { id: unknown, code: unknown }[] = []
+    const lines = createInterface({ input: child.stdout })
+    lines.on('line', (line) => {
+        const value = JSON.parse(line)
+        if (value.error)
+            protocolErrors.push({ id: value.id, code: value.error.code })
+        if (value.id === 1) {
+            send({ method: 'initialized' })
+            send({ id: 2, method: 'account/login/start', params: { type: 'amazonBedrock', apiKey: canary, region: 'us-east-1' } })
+        }
+        if (value.id === 2) {
+            loginResponded = true
+            send({ id: 3, method: 'thread/start', params: { modelProvider: 'amazon-bedrock', model: 'openai.gpt-5.6-terra', cwd: directory, approvalPolicy: 'never', sandbox: 'danger-full-access' } })
+        }
+        if (value.id === 3 && value.result?.thread?.id) {
+            send({ id: 4, method: 'turn/start', params: { threadId: value.result.thread.id, input: [{ type: 'text', text: 'Synthetic offline diagnostic probe. Do not use tools.' }] } })
+        }
+        if (value.id === 4 || value.error) {
+            turnAccepted = value.id === 4 && Boolean(value.result?.turn?.id)
+            // Allow the runtime's asynchronous diagnostic writer to flush.
+            setTimeout(() => child.stdin.end(), 2_000)
+        }
+    })
+    send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'diagnostic-canary-probe', version: '1' }, capabilities: { experimentalApi: true } } })
+    const timeout = setTimeout(() => child.kill('SIGTERM'), 10_000)
+    const exitCode = await exited
+    clearTimeout(timeout)
+    lines.close()
+    const files = await readdir(directory)
+    const logs = files.filter(name => /^logs_\d+\.sqlite$/.test(name))
+    const databases = logs.map((name) => {
+        // These synthetic-only files belong to this probe. SQLite may need to
+        // recreate its WAL shared-memory file after the child exits.
+        const db = new Database(join(directory, name), { readwrite: true, create: false })
+        try {
+            return { name, ...db.query('SELECT count(*) AS records, coalesce(sum(instr(feedback_log_body, ?) > 0), 0) AS canaryRecords FROM logs').get(canary) as { records: number, canaryRecords: number } }
+        }
+        finally { db.close() }
+    })
+    const canaryFiles: string[] = []
+    const skippedFiles: string[] = []
+    let scannedFiles = 0
+    async function scan(relative = ''): Promise<void> {
+        for (const entry of await readdir(join(directory, relative), { withFileTypes: true })) {
+            const path = join(relative, entry.name)
+            if (entry.isDirectory()) {
+                await scan(path)
+            }
+            else if (entry.isFile()) {
+                if ((await stat(join(directory, path))).size > 16 * 1024 * 1024) {
+                    skippedFiles.push(path)
+                    continue
+                }
+                scannedFiles++
+                if ((await readFile(join(directory, path))).includes(canary))
+                    canaryFiles.push(path)
+            }
+        }
+    }
+    await scan()
+    console.log(JSON.stringify({ mode, directory, loginResponded, turnAccepted, protocolErrors, exitCode, stderrHasCanary, databases, scannedFiles, canaryFiles, skippedFiles }))
+    if (!turnAccepted || protocolErrors.length || exitCode !== 0 || stderrHasCanary || canaryFiles.length || skippedFiles.length)
+        process.exitCode = 1
+}

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

@@ -111,6 +111,7 @@ export interface ClaudeEventMapperState {
     interrupt: { status: 'none' } | { status: 'requesting' | 'accepted', turnId: string }
     sessionState?: 'running' | 'idle'
     currentTurnId?: string
+    currentCommandId?: string
     currentMessageId?: string
     currentCompactionId?: string
 }
@@ -213,6 +214,7 @@ export function mapClaudeMessage(message: SDKMessage, state: ClaudeEventMapperSt
         state.turnStarted = false
         state.interrupt = { status: 'none' }
         state.currentTurnId = undefined
+        state.currentCommandId = undefined
         state.currentMessageId = undefined
         state.currentCompactionId = undefined
         return drafts
@@ -522,7 +524,7 @@ function ensureTurnStarted(drafts: AgentEventDraft[], state: ClaudeEventMapperSt
     state.currentTurnId = createRuntimeTurnId()
     state.currentMessageId = undefined
     state.contentBlockTypeByIndex.clear()
-    drafts.push({ type: 'turn.started', turnId: state.currentTurnId, actor: mainActor, payload: {} })
+    drafts.push({ type: 'turn.started', turnId: state.currentTurnId, actor: mainActor, payload: removeUndefined({ commandId: state.currentCommandId }) })
     ensureSessionRunning(drafts, state)
     return state.currentTurnId
 }

package/src/agents/claude/claude-persisted-output.ts

@@ -0,0 +1,65 @@
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk'
+import { Buffer } from 'node:buffer'
+import { constants } from 'node:fs'
+import { open, realpath } from 'node:fs/promises'
+import { basename, dirname, join, resolve } from 'node:path'
+
+const MAX_OUTPUT_BYTES = 16 * 1024 * 1024
+
+export async function hydrateClaudeToolOutput(message: SDKMessage, input: {
+    transcriptPath: string
+    toolNameById: ReadonlyMap<string, string>
+}): Promise<SDKMessage> {
+    if (message.type !== 'user' || !message.tool_use_result || typeof message.tool_use_result !== 'object')
+        return message
+    const result = message.tool_use_result as Record<string, unknown>
+    if (result.persistedOutputPath === undefined)
+        return message
+    const content = message.message.content
+    if (!Array.isArray(content))
+        throw new Error('Claude persisted output has no correlated tool result.')
+    const blocks = content.filter(block => block.type === 'tool_result')
+    if (blocks.length !== 1 || input.toolNameById.get(blocks[0]!.tool_use_id) !== 'bash')
+        throw new Error('Claude persisted output has ambiguous tool correlation.')
+    if (typeof result.persistedOutputPath !== 'string' || typeof result.persistedOutputSize !== 'number')
+        throw new Error('Claude persisted output metadata is malformed.')
+    const text = await readClaudePersistedOutput({ transcriptPath: input.transcriptPath, path: result.persistedOutputPath, byteSize: result.persistedOutputSize })
+    return { ...message, message: { ...message.message, content: content.map(block => block === blocks[0] ? { ...block, content: text } : block) } }
+}
+
+/** Read only the SDK-owned tool-results file, never a path parsed from model text. */
+export async function readClaudePersistedOutput(input: {
+    transcriptPath: string
+    path: string
+    byteSize: number
+}): Promise<string> {
+    const transcript = resolve(input.transcriptPath)
+    const root = join(dirname(transcript), basename(transcript, '.jsonl'), 'tool-results')
+    if (!Number.isSafeInteger(input.byteSize) || input.byteSize < 0 || input.byteSize > MAX_OUTPUT_BYTES)
+        throw new Error('Claude persisted tool output exceeds the bounded capture budget.')
+    if (input.path !== resolve(input.path) || dirname(input.path) !== root || await realpath(root) !== root)
+        throw new Error('Claude persisted tool output is outside its provider session.')
+    const file = await open(input.path, constants.O_RDONLY | constants.O_NOFOLLOW)
+    try {
+        const before = await file.stat()
+        if (!before.isFile() || before.nlink !== 1 || before.size !== input.byteSize)
+            throw new Error('Claude persisted tool output metadata does not match its file.')
+        // Bounded reads also detect growth between stat and read; readFile could
+        // allocate arbitrarily if the file is concurrently extended.
+        const bytes = Buffer.alloc(input.byteSize + 1)
+        let offset = 0
+        while (offset < bytes.length) {
+            const result = await file.read(bytes, offset, bytes.length - offset, offset)
+            if (!result.bytesRead)
+                break
+            offset += result.bytesRead
+        }
+        const after = await file.stat()
+        if (offset !== input.byteSize || after.size !== before.size || after.mtimeMs !== before.mtimeMs)
+            throw new Error('Claude persisted tool output changed during capture.')
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, offset))
+    }
+    finally {
+        await file.close()
+    }
+}

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

@@ -4,6 +4,7 @@ import type { AgentOperationOptions } from '../agent-operation'
 import type { AgentProvider, AgentSessionOpenInput, AgentSessionResumeInput } from '../agent-provider'
 import type { AgentTool } from '../agent-tool'
 import type { InstructionComposer } from '../instructions'
+import type { ClaudeStartupTiming } from './claude-startup-timing'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { query as queryClaude } from '@anthropic-ai/claude-agent-sdk'
@@ -15,6 +16,7 @@ import { removeUndefined } from '../normalize'
 import { UserInputRequestStore, userInputRequestStoreRootFromTranscriptPath } from '../user-input-request'
 import { createClaudeEventMapperState } from './claude-event-mapper'
 import { ClaudeRun } from './claude-run'
+import { createClaudeStartupTiming, observeClaudeControlInitialization } from './claude-startup-timing'
 import { claudeAllowedToolNames, claudeToolActorHooks, createClaudeToolRuntimeRef, toClaudeMcpServers } from './claude-tool-mapper'
 
 export interface ClaudeProviderConfig {
@@ -22,6 +24,7 @@ export interface ClaudeProviderConfig {
     executable?: string
     environment?: Record<string, string | undefined>
     instructions?: InstructionComposer
+    onStartupTiming?: (timing: ClaudeStartupTiming) => void
 }
 
 export class ClaudeProvider implements AgentProvider<'claude'> {
@@ -30,12 +33,14 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
     private readonly executable: string | undefined
     private readonly environment: Record<string, string | undefined>
     private readonly instructions: InstructionComposer
+    private readonly onStartupTiming: ClaudeProviderConfig['onStartupTiming']
 
     private constructor(config: ClaudeProviderConfig) {
         this.tools = config.tools ?? []
         this.executable = config.executable
         this.environment = config.environment ?? {}
         this.instructions = config.instructions ?? emptyInstructionComposer
+        this.onStartupTiming = config.onStartupTiming
     }
 
     static create(config: ClaudeProviderConfig = {}): ClaudeProvider {
@@ -96,7 +101,11 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
             pathToClaudeCodeExecutable: this.executable,
         })
 
+        const recordStartup = createClaudeStartupTiming(this.onStartupTiming)
         const query = queryClaude({ prompt: inputQueue, options: sdkOptions })
+        recordStartup('query_created')
+        if (this.onStartupTiming)
+            observeClaudeControlInitialization(query.initializationResult(), recordStartup)
         try {
             // Binding metadata comes from pre-input facts only: the live runtime emits system/init
             // only after the first user message, so the run validates identity/config on the first
@@ -122,6 +131,7 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
                 userInputRequests,
                 input: inputQueue,
                 eventMapperState: state,
+                recordStartup,
                 init: {
                     expectedSessionId,
                     requestedModel: input.model,

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

@@ -13,14 +13,16 @@ import type { AgentOperationOptions } from '../agent-operation'
 import type { AgentPromptAcceptance, AgentRun, AgentUserInputSubmission } from '../agent-run'
 import type { UserInputRequestInput, UserInputRequestStore } from '../user-input-request'
 import type { ClaudeEventMapperState } from './claude-event-mapper'
+import type { ClaudeStartupPhase } from './claude-startup-timing'
 import z from 'zod'
 import { serializeAgentError } from '../agent-error-serializer'
 import { AgentEventStream } from '../agent-event-stream'
-import { AgentDeliveryUnknownError, AgentNotAcceptedError, AgentProviderMetadataError, AgentProviderProtocolError, AgentRunStateError } from '../agent-runtime-error'
+import { AgentDeliveryUnknownError, AgentNotAcceptedError, AgentPromptDeferredError, AgentProviderMetadataError, AgentProviderProtocolError, AgentRunStateError } from '../agent-runtime-error'
 import { sessionConfiguredEvent } from '../agent-session-events'
 import { deriveMessageId } from '../message-id'
 import { mapClaudeUserMessage, toClaudeUserMessage } from './claude-command-mapper'
 import { mapClaudeMessage } from './claude-event-mapper'
+import { hydrateClaudeToolOutput } from './claude-persisted-output'
 
 // The ONE long-lived SDK input stream created with the query. SDK 0.3.207 Query.streamInput ends
 // stdin after any finite iterable and the transport silently drops later writes, so every user
@@ -77,6 +79,7 @@ interface ClaudeRunInput {
     input: ClaudeInputStream
     eventMapperState: ClaudeEventMapperState
     init: ClaudeInitExpectation
+    recordStartup?: (phase: ClaudeStartupPhase) => void
 }
 
 export class ClaudeRun implements AgentRun {
@@ -87,22 +90,27 @@ 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 initializationReject: (error: unknown) => void = () => undefined
     private initialized = false
     private firstInputPushed = false
+    private modelChangeReady = true
+    private modelChangeInFlight = false
     private finished = false
     private interruptRequest?: { turnId: string, promise: Promise<void> }
     private readonly acceptanceWaiters = new Map<string, AcceptanceWaiter>()
+    private readonly commandByClientMessageId = new Map<string, string>()
 
-    constructor({ metadata, query, userInputRequests, input, eventMapperState, init }: ClaudeRunInput) {
+    constructor({ metadata, query, userInputRequests, input, eventMapperState, init, recordStartup }: ClaudeRunInput) {
         this.metadata = metadata
         this.query = query
         this.userInputRequests = userInputRequests
         this.input = input
         this.eventMapperState = eventMapperState
         this.init = init
+        this.recordStartup = recordStartup
         this.initialization = new Promise<void>((resolve, reject) => {
             this.initializationResolve = resolve
             this.initializationReject = reject
@@ -129,6 +137,10 @@ export class ClaudeRun implements AgentRun {
     pushEvent(draft: AgentEventDraft): void {
         if (this.finished)
             return
+        if (draft.type === 'turn.started')
+            this.modelChangeReady = false
+        if (draft.type === 'session.state.changed' && draft.payload.state === 'idle')
+            this.modelChangeReady = true
         const decorated = this.userInputRequests.decorateTurnEnded(draft)
         if (decorated.type === 'session.state.changed' && decorated.payload.state === 'idle' && this.userInputRequests.shouldHoldIdle()) {
             this.events.push({ type: 'session.state.changed', payload: { state: 'waiting_for_user_input' } })
@@ -160,10 +172,31 @@ export class ClaudeRun implements AgentRun {
         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()
+        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)
+            }
+            finally {
+                this.modelChangeInFlight = false
+            }
+            this.metadata.model = command.model
+            this.init.requestedModel = command.model
+            options.signal?.throwIfAborted()
+        }
+        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.
         const clientMessageId = deriveMessageId(command.commandId)
         const receipt = this.registerAcceptanceWaiter(clientMessageId)
+        this.commandByClientMessageId.set(clientMessageId, command.commandId)
         try {
             await this.deliverInput(message)
             // `submitted` requires the provider's positive acceptance receipt — the pinned
@@ -257,6 +290,7 @@ export class ClaudeRun implements AgentRun {
             }))
         }
         this.acceptanceWaiters.clear()
+        this.commandByClientMessageId.clear()
         this.events.push({ type: 'session.ended', payload: error ? { reason, error } : { reason } })
         this.events.push({ type: 'session.state.changed', payload: { state: reason === 'failed' ? 'failed' : 'stopped' } })
         this.events.end()
@@ -306,8 +340,17 @@ export class ClaudeRun implements AgentRun {
             this.acceptanceWaiters.get(parsed.data.command_uuid)?.reject(new AgentDeliveryUnknownError({
                 message: `Claude command ended as ${parsed.data.state} before acceptance was observed.`,
             }))
+            this.commandByClientMessageId.delete(parsed.data.command_uuid)
             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') {
+            this.eventMapperState.currentCommandId = this.commandByClientMessageId.get(parsed.data.command_uuid)
+        }
+        if (parsed.data.state === 'completed')
+            this.commandByClientMessageId.delete(parsed.data.command_uuid)
         this.acceptanceWaiters.get(parsed.data.command_uuid)?.resolve()
     }
 
@@ -362,6 +405,7 @@ export class ClaudeRun implements AgentRun {
     private async pushOwnedStream(message: SDKUserMessage): Promise<void> {
         try {
             await this.input.push(message)
+            this.recordStartup?.('first_input_queued')
         }
         catch (error) {
             if (error instanceof AgentRunStateError) {
@@ -389,7 +433,13 @@ export class ClaudeRun implements AgentRun {
                     this.completeInitialization(message)
                     continue
                 }
-                for (const draft of mapClaudeMessage(message, this.eventMapperState)) this.pushEvent(draft)
+                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)
             }
             // An intentional stop already finalized the run; the ended stream is expected then.
             if (this.finished)
@@ -425,6 +475,7 @@ export class ClaudeRun implements AgentRun {
         if (!effectiveModel) {
             throw new AgentProviderMetadataError({ message: 'Claude SDK init did not include model.', details: { provider: 'claude' } })
         }
+        this.metadata.model = effectiveModel
 
         this.pushEvent({ type: 'session.started', payload: this.metadata })
         this.pushEvent(sessionConfiguredEvent({
@@ -437,6 +488,7 @@ export class ClaudeRun implements AgentRun {
         this.pushEvent({ type: 'session.state.changed', payload: { state: 'ready' } })
         for (const draft of mapClaudeMessage(init, this.eventMapperState)) this.pushEvent(draft)
         this.initialized = true
+        this.recordStartup?.('session_ready')
         this.initializationResolve()
     }
 

package/src/agents/claude/claude-startup-timing.ts

@@ -0,0 +1,34 @@
+export type ClaudeStartupPhase = 'query_created' | 'control_ready' | 'control_failed' | 'first_input_queued' | 'session_ready'
+
+export interface ClaudeStartupTiming {
+    phase: ClaudeStartupPhase
+    elapsedMs: number
+}
+
+/** Payload-free diagnostics only; never becomes an execution readiness barrier. */
+export function createClaudeStartupTiming(
+    observer?: (timing: ClaudeStartupTiming) => void,
+    now: () => number = () => performance.now(),
+): (phase: ClaudeStartupPhase) => void {
+    const started = now()
+    const seen = new Set<ClaudeStartupPhase>()
+    return (phase) => {
+        if (!observer || seen.has(phase))
+            return
+        seen.add(phase)
+        try {
+            observer({ phase, elapsedMs: Math.max(0, now() - started) })
+        }
+        catch {
+            // Observability must not reject a command or stop the provider stream.
+        }
+    }
+}
+
+export function observeClaudeControlInitialization(
+    initialization: Promise<unknown>,
+    record: (phase: ClaudeStartupPhase) => void,
+): void {
+    // Discard account/configuration response and error bodies, which may be sensitive.
+    void initialization.then(() => record('control_ready'), () => record('control_failed'))
+}

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

@@ -29,6 +29,17 @@ export interface CodexApiKeyAuthProvider {
     getApiKey: (input?: CodexAuthTokenRequest) => Promise<CodexApiKeyCredentials>
 }
 
+export interface CodexBedrockCredentials {
+    bearerToken: string
+    expiresAt: number
+    generation: number
+}
+
+export interface CodexBedrockAuthProvider {
+    getCredentials: (input?: CodexAuthTokenRequest) => Promise<CodexBedrockCredentials>
+}
+
 export type CodexAuthentication
     = | { kind: 'chatgpt', provider: CodexAuthProvider }
         | { kind: 'api-key', provider: CodexApiKeyAuthProvider, modelProvider?: string }
+        | { kind: 'amazon-bedrock', region: string, provider: CodexBedrockAuthProvider }

package/src/agents/codex/codex-bedrock-diagnostics.ts

@@ -0,0 +1,6 @@
+/** Raw runtime diagnostics can contain bearer credentials and request bodies. */
+export function bedrockDiagnosticMessage(source: 'stderr' | 'invalid-json-rpc'): string {
+    return source === 'stderr'
+        ? 'Codex emitted a provider diagnostic; raw content withheld.'
+        : 'Codex emitted an invalid JSON-RPC line; raw content withheld.'
+}

package/src/agents/codex/codex-bedrock-session-auth.ts

@@ -0,0 +1,79 @@
+import type { CodexBedrockAuthProvider, CodexBedrockCredentials } from './codex-auth'
+import { AgentPromptDeferredError, AgentProviderRuntimeError } from '../agent-runtime-error'
+
+export function validateBedrockCredentials(credentials: CodexBedrockCredentials, now = Date.now()): void {
+    if (!credentials.bearerToken || !Number.isFinite(credentials.expiresAt) || credentials.expiresAt <= now
+        || !Number.isSafeInteger(credentials.generation) || credentials.generation < 1) {
+        throw new AgentProviderRuntimeError({ message: 'Codex Bedrock credentials are invalid or expired.' })
+    }
+}
+
+/** Updates authentication only; never dispatches or retries a provider prompt. */
+export class CodexBedrockSessionAuth {
+    private current: CodexBedrockCredentials
+    private pending: Promise<void> | undefined
+    private terminalFailure: Error | undefined
+
+    constructor(private readonly input: {
+        initial: CodexBedrockCredentials
+        provider: CodexBedrockAuthProvider
+        login: (credentials: CodexBedrockCredentials) => Promise<void>
+        isActive: () => boolean
+        now?: () => number
+        refreshTimeoutMs?: number
+    }) {
+        this.current = { ...input.initial }
+    }
+
+    async beforePrompt(signal?: AbortSignal): Promise<void> {
+        signal?.throwIfAborted()
+        if (this.terminalFailure)
+            throw this.terminalFailure
+        const now = this.input.now ?? Date.now
+        if (this.current.expiresAt - now() > 5 * 60_000)
+            return
+        if (this.input.isActive())
+            throw new AgentPromptDeferredError({ message: 'Bedrock credential refresh requires an idle turn boundary.' })
+        this.pending ??= this.boundedRefresh(now).finally(() => {
+            this.pending = undefined
+        })
+        await this.pending
+        signal?.throwIfAborted()
+    }
+
+    private async boundedRefresh(now: () => number): Promise<void> {
+        const abort = new AbortController()
+        let timer: ReturnType<typeof setTimeout> | undefined
+        const deadline = new Promise<never>((_resolve, reject) => {
+            timer = setTimeout(() => {
+                this.terminalFailure = new AgentProviderRuntimeError({ message: 'Bedrock authentication refresh timed out; the provider connection must be reopened before dispatch.' })
+                abort.abort(this.terminalFailure)
+                reject(this.terminalFailure)
+            }, this.input.refreshTimeoutMs ?? 30_000)
+        })
+        try {
+            await Promise.race([this.refresh(now, abort.signal), deadline])
+        }
+        finally {
+            clearTimeout(timer)
+        }
+    }
+
+    private async refresh(now: () => number, signal: AbortSignal): Promise<void> {
+        // A caller abort must not cancel refresh shared by other pending callers.
+        const credentials = await this.input.provider.getCredentials({ signal })
+        signal.throwIfAborted()
+        validateBedrockCredentials(credentials, now())
+        if (credentials.expiresAt - now() <= 5 * 60_000)
+            throw new AgentProviderRuntimeError({ message: 'Bedrock credentials expire inside the refresh window.' })
+        if (credentials.generation < this.current.generation
+            || (credentials.generation === this.current.generation && (credentials.bearerToken !== this.current.bearerToken || credentials.expiresAt !== this.current.expiresAt))) {
+            throw new AgentProviderRuntimeError({ message: 'Bedrock credential generation is stale or conflicting.' })
+        }
+        if (this.input.isActive())
+            throw new AgentPromptDeferredError({ message: 'Bedrock credential refresh raced an active turn.' })
+        await this.input.login(credentials)
+        signal.throwIfAborted()
+        this.current = { ...credentials }
+    }
+}

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

@@ -399,8 +399,10 @@ function hookPromptText(item: CodexHookPromptItem): string | undefined {
 }
 
 function commandExecutionResult(item: Extract<CodexCompletedItem, { type: 'commandExecution' }>, status: 'completed' | 'failed'): AgentToolResult | undefined {
-    const text = optionalNonEmpty(item.aggregatedOutput ?? undefined)
-    if (!text)
+    // Stdout is content, not a label: whitespace and an explicitly empty
+    // successful output must survive normalization into the complete step.
+    const text = item.aggregatedOutput
+    if (typeof text !== 'string')
         return undefined
 
     return { success: status === 'completed', content: [{ type: 'text', text }] }

package/src/agents/codex/codex-json-rpc-client.ts

@@ -70,12 +70,13 @@ export class CodexJsonRpcClient {
         options: {
             cwd: string
             environment?: Record<string, string | undefined>
+            configOverrides?: readonly string[]
             onMessage: (message: CodexJsonRpcMessage) => void
             onInvalidLine: (line: string, error: unknown) => void
             onStderr: (line: string) => void
         },
     ) {
-        this.child = spawn(executable, ['app-server', '--listen', 'stdio://'], {
+        this.child = spawn(executable, ['app-server', '--listen', 'stdio://', ...(options.configOverrides ?? []).flatMap(value => ['-c', value])], {
             cwd: options.cwd,
             env: options.environment,
             stdio: 'pipe',

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

@@ -1,9 +1,10 @@
 import type { AgentReasoningEffort, AgentToolDefinition, CodexModelId } from '../../protocol'
 import type { AgentOperationOptions } from '../agent-operation'
 import type { AgentProvider, AgentSessionOpenInput, AgentSessionResumeInput } from '../agent-provider'
+import type { AgentRun } from '../agent-run'
 import type { AgentTool } from '../agent-tool'
 import type { InstructionComposer } from '../instructions'
-import type { CodexAuthentication, CodexAuthProvider, CodexAuthRefreshInput, CodexAuthTokens } from './codex-auth'
+import type { CodexAuthentication, CodexAuthProvider, CodexAuthRefreshInput, CodexAuthTokens, CodexBedrockCredentials } from './codex-auth'
 import type { CodexEventMapperState, CodexNotification } from './codex-event-mapper'
 import type { CodexJsonRpcMessage, CodexServerRequest } from './codex-json-rpc-client'
 import type { ClientRequestResponsesByMethod, CodexChatGPTAuthTokensRefreshParams } from './codex-protocol'
@@ -16,7 +17,10 @@ import { AgentNotAcceptedError, AgentProviderMetadataError, AgentProviderProtoco
 import { sessionConfiguredEvent } from '../agent-session-events'
 import { selectAgentTools, toolByName } from '../agent-tool'
 import { emptyInstructionComposer } from '../instructions'
+import { ModelRebindingRun } from '../model-rebinding-run'
 import { UserInputRequestStore, userInputRequestStoreRootFromTranscriptPath } from '../user-input-request'
+import { bedrockDiagnosticMessage } from './codex-bedrock-diagnostics'
+import { CodexBedrockSessionAuth, validateBedrockCredentials } from './codex-bedrock-session-auth'
 import { cacheCodexThreadMetadata, codexNotificationFromMessage, createCodexEventMapperState, mapCodexNotification } from './codex-event-mapper'
 import { CodexJsonRpcClient, isCodexServerRequest } from './codex-json-rpc-client'
 import { CodexRun } from './codex-run'
@@ -38,17 +42,21 @@ export interface CodexProviderConfig {
     environment?: Record<string, string | undefined>
     onStartupStage?: (fact: CodexStartupStageFact) => void
     instructions?: InstructionComposer
+    /** Service-owned public model to inference model mapping. */
+    resolveInferenceModel?: (model: string) => string
 }
 
 interface CodexRunHolder {
     toolsByName: Map<string, AgentTool>
     run?: CodexRun
     authTokens?: CodexAuthTokens
+    bedrockAuth?: CodexBedrockSessionAuth
     startupFailure?: Error
 }
 type CodexAuthMaterial
     = | { kind: 'chatgpt', tokens: CodexAuthTokens }
         | { kind: 'api-key', apiKey: string }
+        | { kind: 'amazon-bedrock', region: string, credentials: CodexBedrockCredentials }
 interface CodexConnection {
     client: CodexJsonRpcClient
     abortController: AbortController
@@ -78,6 +86,8 @@ export class CodexProvider implements AgentProvider<'codex'> {
     private readonly auth: CodexAuthentication
     private readonly onStartupStage: ((fact: CodexStartupStageFact) => void) | undefined
     private readonly instructions: InstructionComposer
+    private readonly resolveInferenceModel: (model: string) => string
+    private readonly hasInferenceModelMapping: boolean
 
     private constructor(config: CodexProviderConfig) {
         this.auth = normalizeCodexAuthentication(config.auth)
@@ -86,21 +96,23 @@ export class CodexProvider implements AgentProvider<'codex'> {
         this.environment = config.environment ?? {}
         this.onStartupStage = config.onStartupStage
         this.instructions = config.instructions ?? emptyInstructionComposer
+        this.resolveInferenceModel = config.resolveInferenceModel ?? (model => model)
+        this.hasInferenceModelMapping = config.resolveInferenceModel !== undefined
     }
 
     static create(config: CodexProviderConfig): CodexProvider {
         return new CodexProvider(config)
     }
 
-    async openSession(input: AgentSessionOpenInput<'codex'>, options: AgentOperationOptions = {}): Promise<CodexRun> {
-        return await this.startSession({
+    async openSession(input: AgentSessionOpenInput<'codex'>, options: AgentOperationOptions = {}): Promise<AgentRun> {
+        const run = await this.startSession({
             config: input,
             options,
             stage: 'thread-start',
             requestThread: async ({ client, tools }): Promise<CodexThreadBootstrapResult> => await client.request('thread/start', {
                 cwd: input.cwd,
-                model: input.model,
-                modelProvider: this.auth.kind === 'api-key' ? this.auth.modelProvider : undefined,
+                model: input.model ? this.resolveInferenceModel(input.model) : undefined,
+                modelProvider: this.modelProvider(),
                 ephemeral: false,
                 approvalPolicy: 'never',
                 sandbox: 'danger-full-access',
@@ -108,9 +120,26 @@ export class CodexProvider implements AgentProvider<'codex'> {
                 dynamicTools: toCodexDynamicTools(tools),
             }),
         })
+        return this.wrapBedrockRun(run, input)
+    }
+
+    async resumeSession(input: AgentSessionResumeInput<'codex'>, options: AgentOperationOptions = {}): Promise<AgentRun> {
+        return this.wrapBedrockRun(await this.resumeRawSession(input, options), input)
+    }
+
+    private wrapBedrockRun(run: CodexRun, input: AgentSessionOpenInput<'codex'>): AgentRun {
+        if (this.auth.kind !== 'amazon-bedrock')
+            return run
+        const roots = new Set(input.workspaceRepositoryRoots)
+        return new ModelRebindingRun(run, async (model, signal) => await this.resumeRawSession({
+            ...input,
+            model: codexModelIdSchema.parse(model),
+            providerSessionId: run.metadata.providerSessionId,
+            workspaceRepositoryRoots: [...roots],
+        }, { signal }), root => roots.add(root))
     }
 
-    async resumeSession(input: AgentSessionResumeInput<'codex'>, options: AgentOperationOptions = {}): Promise<CodexRun> {
+    private async resumeRawSession(input: AgentSessionResumeInput<'codex'>, options: AgentOperationOptions = {}): Promise<CodexRun> {
         return await this.startSession({
             config: input,
             options,
@@ -120,8 +149,8 @@ export class CodexProvider implements AgentProvider<'codex'> {
                 cwd: input.cwd,
                 approvalPolicy: 'never',
                 sandbox: 'danger-full-access',
-                model: input.model,
-                modelProvider: this.auth.kind === 'api-key' ? this.auth.modelProvider : undefined,
+                model: input.model ? this.resolveInferenceModel(input.model) : undefined,
+                modelProvider: this.modelProvider(),
                 developerInstructions: this.instructions({ provider: 'codex', tools }),
             }),
             validateThread: (result) => {
@@ -320,6 +349,12 @@ export class CodexProvider implements AgentProvider<'codex'> {
     }
 
     private async getAuthMaterial(signal: AbortSignal): Promise<CodexAuthMaterial> {
+        if (this.auth.kind === 'amazon-bedrock') {
+            const credentials = await this.auth.provider.getCredentials({ signal })
+            signal.throwIfAborted()
+            validateBedrockCredentials(credentials)
+            return { kind: 'amazon-bedrock', region: this.auth.region, credentials }
+        }
         if (this.auth.kind === 'api-key') {
             const credentials = await this.auth.provider.getApiKey({ signal })
             return { kind: 'api-key', apiKey: credentials.apiKey }
@@ -328,6 +363,10 @@ export class CodexProvider implements AgentProvider<'codex'> {
         return { kind: 'chatgpt', tokens }
     }
 
+    private modelProvider(): string | undefined {
+        return this.auth.kind === 'amazon-bedrock' ? 'amazon-bedrock' : this.auth.kind === 'api-key' ? this.auth.modelProvider : undefined
+    }
+
     private async openConnection(input: {
         sessionId: string
         cwd: string
@@ -347,11 +386,19 @@ export class CodexProvider implements AgentProvider<'codex'> {
             client = new CodexJsonRpcClient(this.executable, {
                 cwd,
                 environment: this.environment,
+                configOverrides: this.auth.kind === 'amazon-bedrock'
+                    ? ['cli_auth_credentials_store="ephemeral"', 'model_provider="amazon-bedrock"', `model_providers.amazon-bedrock.aws.region=${JSON.stringify(this.auth.region)}`, 'model_providers.amazon-bedrock.aws.wire_api="responses"']
+                    : undefined,
                 onMessage: (message) => {
                     messageQueue = this.enqueueMessageHandling(messageQueue, { message, holder, state, client, signal: abortController.signal })
                 },
-                onInvalidLine: (line, error) => holder.run?.pushEvent({ type: 'error', payload: { message: `Invalid Codex JSON-RPC line: ${line.slice(0, 200)}`, fatal: false, source: 'transport', error: serializeAgentError(error) } }),
-                onStderr: line => holder.run?.pushEvent({ type: 'error', payload: { message: line, fatal: false, source: 'provider' } }),
+                onInvalidLine: (line, error) => holder.run?.pushEvent({
+                    type: 'error',
+                    payload: this.auth.kind === 'amazon-bedrock'
+                        ? { message: bedrockDiagnosticMessage('invalid-json-rpc'), fatal: false, source: 'transport' }
+                        : { message: `Invalid Codex JSON-RPC line: ${line.slice(0, 200)}`, fatal: false, source: 'transport', error: serializeAgentError(error) },
+                }),
+                onStderr: line => holder.run?.pushEvent({ type: 'error', payload: { message: this.auth.kind === 'amazon-bedrock' ? bedrockDiagnosticMessage('stderr') : line, fatal: false, source: 'provider' } }),
             })
         }
         catch (error) {
@@ -483,12 +530,15 @@ export class CodexProvider implements AgentProvider<'codex'> {
             })
         }
 
+        if (this.hasInferenceModelMapping && config.model && result.model && result.model !== this.resolveInferenceModel(config.model))
+            throw new AgentProviderProtocolError({ message: 'Codex returned a model that does not match the configured inference binding.' })
+
         const metadata = {
             provider: 'codex' as const,
             sessionId: config.sessionId,
             providerSessionId: thread.id,
             cwd: thread.cwd ?? config.cwd,
-            model: firstCodexModelId(effectiveModel),
+            model: firstCodexModelId(this.hasInferenceModelMapping ? config.model ?? effectiveModel : effectiveModel),
             transcriptPath: thread.path,
         }
         throwIfStartupFailed(holder)
@@ -507,8 +557,10 @@ export class CodexProvider implements AgentProvider<'codex'> {
         ])
         startupSignal?.throwIfAborted()
         const run = new CodexRun({
+            beforePrompt: holder.bedrockAuth ? signal => holder.bedrockAuth!.beforePrompt(signal) : undefined,
             metadata,
             reasoningEffort: config.reasoningEffort,
+            resolveInferenceModel: this.resolveInferenceModel,
             client,
             requestedCwd: config.cwd,
             workspaceRepositoryRoots: config.workspaceRepositoryRoots,
@@ -529,7 +581,7 @@ export class CodexProvider implements AgentProvider<'codex'> {
         holder.run = run
 
         run.pushEvent({ type: 'session.started', payload: run.metadata })
-        run.pushEvent(sessionConfiguredEvent({ model: effectiveModel, cwd: run.metadata.cwd, reasoningEffort: config.reasoningEffort, tools: config.tools, environment: this.environment }))
+        run.pushEvent(sessionConfiguredEvent({ model: run.metadata.model ?? effectiveModel, cwd: run.metadata.cwd, reasoningEffort: config.reasoningEffort, tools: config.tools, environment: this.environment }))
         run.pushEvent({ type: 'session.state.changed', payload: { state: 'ready' } })
         return run
     }
@@ -615,6 +667,23 @@ export class CodexProvider implements AgentProvider<'codex'> {
     }): Promise<void> {
         const { client, holder, authMaterial } = input
         throwIfStartupFailed(holder)
+        if (authMaterial.kind === 'amazon-bedrock') {
+            if (authMaterial.credentials.expiresAt <= Date.now())
+                throw new AgentProviderRuntimeError({ message: 'Codex Bedrock credentials expired before login.' })
+            await client.request('account/login/start', { type: 'amazonBedrock', apiKey: authMaterial.credentials.bearerToken, region: authMaterial.region })
+            throwIfStartupFailed(holder)
+            if (this.auth.kind !== 'amazon-bedrock')
+                throw new AgentProviderProtocolError({ message: 'Bedrock authentication mode changed during login.' })
+            holder.bedrockAuth = new CodexBedrockSessionAuth({
+                initial: authMaterial.credentials,
+                provider: this.auth.provider,
+                isActive: () => holder.run?.hasActiveTurn() ?? false,
+                login: async (credentials) => {
+                    await client.request('account/login/start', { type: 'amazonBedrock', apiKey: credentials.bearerToken, region: authMaterial.region })
+                },
+            })
+            return
+        }
         if (authMaterial.kind === 'api-key') {
             await client.request('account/login/start', { type: 'apiKey', apiKey: authMaterial.apiKey })
             throwIfStartupFailed(holder)

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

@@ -35,9 +35,12 @@ interface PreparedCodexTurn {
     input: CodexUserInput[]
     commandId: string
     origin: 'user' | 'supervisor'
+    model?: string
 }
 
 interface CodexRunInput {
+    beforePrompt?: (signal?: AbortSignal) => Promise<void>
+    resolveInferenceModel?: (model: string) => string
     metadata: AgentRunMetadata
     reasoningEffort?: AgentReasoningEffort
     client: CodexJsonRpcClient
@@ -56,6 +59,8 @@ export class CodexRun implements AgentRun {
     readonly events: AgentEventStream
     readonly metadata: AgentRunMetadata
     private readonly client: CodexJsonRpcClient
+    private readonly beforePrompt: ((signal?: AbortSignal) => Promise<void>) | undefined
+    private readonly resolveInferenceModel: (model: string) => string
     private readonly reasoningEffort: AgentReasoningEffort | undefined
     private readonly onStop: () => void
     private readonly userInputRequests: UserInputRequestStore
@@ -74,6 +79,8 @@ export class CodexRun implements AgentRun {
     constructor(input: CodexRunInput) {
         this.metadata = input.metadata
         this.client = input.client
+        this.beforePrompt = input.beforePrompt
+        this.resolveInferenceModel = input.resolveInferenceModel ?? (model => model)
         this.reasoningEffort = input.reasoningEffort
         this.onStop = input.onStop
         this.userInputRequests = input.userInputRequests
@@ -225,6 +232,10 @@ export class CodexRun implements AgentRun {
         // 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)
+            await this.beforePrompt(options.signal)
+        this.assertRunning()
+        this.deferNextWhileTurnActive(command.mode)
         const prepared = await this.prepareTurn({
             prompt: command.prompt,
             commandId: command.commandId,
@@ -232,10 +243,13 @@ export class CodexRun implements AgentRun {
             author: command.author,
             options,
         })
+        prepared.model = command.model
         // A turn/started fact may have reduced during attachment preparation.
         this.deferNextWhileTurnActive(command.mode)
 
         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 (command.mode === 'next' || !activeTurnId)
             return await this.startPreparedTurn(prepared)
 
@@ -261,6 +275,10 @@ export class CodexRun implements AgentRun {
         return { kind: 'turn', turnId: result.turnId, placement: 'steered' }
     }
 
+    hasActiveTurn(): boolean {
+        return this.activeTurnId !== undefined
+    }
+
     private deferNextWhileTurnActive(mode: SendPromptCommand['mode']): void {
         if (mode !== 'next' || !this.activeTurnId)
             return
@@ -336,6 +354,8 @@ export class CodexRun implements AgentRun {
     }
 
     private async startPreparedTurn(prepared: PreparedCodexTurn): Promise<AgentPromptAcceptance> {
+        const publicModel = prepared.model ?? this.metadata.model
+        const inferenceModel = publicModel ? this.resolveInferenceModel(publicModel) : undefined
         const clientUserMessageId = this.rememberPromptCommand(prepared.commandId, prepared.origin)
         let result: ClientRequestResponsesByMethod['turn/start']
         try {
@@ -343,7 +363,7 @@ export class CodexRun implements AgentRun {
                 threadId: this.metadata.providerSessionId,
                 input: prepared.input,
                 cwd: this.metadata.cwd,
-                model: this.metadata.model,
+                model: inferenceModel,
                 effort: codexEffort(this.reasoningEffort),
                 summary: codexReasoningSummary,
                 approvalPolicy: 'never',
@@ -355,6 +375,8 @@ export class CodexRun implements AgentRun {
             throw mapTurnTransportLoss(error)
         }
         this.activeTurnId = result.turn.id
+        if (prepared.model)
+            this.metadata.model = prepared.model
         return { kind: 'turn', turnId: result.turn.id, placement: 'started' }
     }
 

package/src/agents/model-rebinding-run.ts

@@ -0,0 +1,166 @@
+import type { AgentEvent, AgentRunMetadata, SendPromptCommand } from '../protocol'
+import type { AgentOperationOptions } from './agent-operation'
+import type { AgentPromptAcceptance, AgentRun } from './agent-run'
+import { AgentEventStream } from './agent-event-stream'
+import { AgentNotAcceptedError, AgentPromptDeferredError, AgentRunStateError } from './agent-runtime-error'
+
+/** Keeps one public event stream while replacing an idle provider connection. */
+export class ModelRebindingRun implements AgentRun {
+    readonly events: AgentEventStream
+    readonly metadata: AgentRunMetadata
+    private run: AgentRun
+    private pump: Promise<void>
+    private activeTurn: string | undefined
+    private lastEndedTurn: string | undefined
+    private dispatching: Promise<AgentPromptAcceptance> | undefined
+    private changing = false
+    private needsRebind = false
+    private stopped = false
+    private workspacePrepared = false
+    private workspaceChanging = false
+    private readonly lifetime = new AbortController()
+
+    constructor(run: AgentRun, private readonly reopen: (model: string, signal: AbortSignal) => Promise<AgentRun>, private readonly rootAdded?: (root: string) => void) {
+        this.run = run
+        this.metadata = { ...run.metadata }
+        this.events = new AgentEventStream(this.metadata)
+        this.pump = this.consume(run)
+    }
+
+    prepareWorkspace: AgentRun['prepareWorkspace'] = async (options) => {
+        await this.withWorkspaceChange(async () => {
+            await this.run.prepareWorkspace(options)
+            this.workspacePrepared = true
+        })
+    }
+
+    addWorkspaceRepositoryRoot: AgentRun['addWorkspaceRepositoryRoot'] = async (root, options) => {
+        await this.withWorkspaceChange(async () => {
+            await this.run.addWorkspaceRepositoryRoot(root, options)
+            this.rootAdded?.(root)
+        })
+    }
+
+    respondUserInput: AgentRun['respondUserInput'] = async (command, options) => await this.run.respondUserInput(command, options)
+    interrupt: AgentRun['interrupt'] = async (command, options) => await this.run.interrupt(command, options)
+
+    async sendPrompt(command: SendPromptCommand, options: AgentOperationOptions = {}): Promise<AgentPromptAcceptance> {
+        if (this.dispatching || this.workspaceChanging)
+            throw new AgentPromptDeferredError({ message: 'A prompt admission is already in progress.' })
+        const task = this.dispatchPrompt(command, options)
+        this.dispatching = task
+        try {
+            return await task
+        }
+        finally { this.dispatching = undefined }
+    }
+
+    private async dispatchPrompt(command: SendPromptCommand, options: AgentOperationOptions): Promise<AgentPromptAcceptance> {
+        if (this.stopped)
+            throw new AgentRunStateError({ message: 'Cannot send a prompt after the run stopped.' })
+        if (command.sessionId !== this.metadata.sessionId || command.providerSessionId !== this.metadata.providerSessionId || command.provider !== this.metadata.provider)
+            throw new AgentRunStateError({ message: 'Prompt does not target the bound run.' })
+        if (this.changing)
+            throw new AgentPromptDeferredError({ message: 'The provider model is being rebound.' })
+        const model = command.model ?? this.metadata.model
+        if (model && (this.needsRebind || model !== this.metadata.model)) {
+            if (this.activeTurn)
+                throw new AgentPromptDeferredError({ message: 'Model changes require an idle turn boundary.' })
+            this.changing = true
+            const signal = AbortSignal.any([this.lifetime.signal, ...(options.signal ? [options.signal] : []), AbortSignal.timeout(10_000)])
+            let replacement: AgentRun | undefined
+            let identityMismatch = false
+            try {
+                signal.throwIfAborted()
+                this.needsRebind = true
+                await this.run.stop({ type: 'agent.stop', ...this.target(), reason: 'model_rebind' }, { signal })
+                await this.pump
+                signal.throwIfAborted()
+                replacement = await this.reopen(model, signal)
+                signal.throwIfAborted()
+                if (replacement.metadata.providerSessionId !== this.metadata.providerSessionId || replacement.metadata.sessionId !== this.metadata.sessionId || replacement.metadata.provider !== this.metadata.provider || replacement.metadata.model !== model) {
+                    identityMismatch = true
+                    throw new Error('Provider rebind changed the persisted identity or model.')
+                }
+                if (this.workspacePrepared)
+                    await replacement.prepareWorkspace({ signal })
+                signal.throwIfAborted()
+                this.run = replacement
+                this.metadata.model = replacement.metadata.model
+                this.needsRebind = false
+                this.pump = this.consume(replacement, true)
+            }
+            catch {
+                if (replacement)
+                    await replacement.stop({ type: 'agent.stop', provider: replacement.metadata.provider, sessionId: replacement.metadata.sessionId, providerSessionId: replacement.metadata.providerSessionId, reason: 'model_rebind_failed' }).catch(() => undefined)
+                throw new AgentNotAcceptedError({ message: 'Provider model rebind failed before prompt dispatch.', recovery: identityMismatch ? { kind: 'terminal', reason: 'model_rebind_identity_mismatch' } : { kind: 'retry', reason: 'model_rebind_failed', retryAfterMs: 1_000 } })
+            }
+            finally {
+                this.changing = false
+            }
+        }
+        this.lifetime.signal.throwIfAborted()
+        options.signal?.throwIfAborted()
+        const acceptance = await this.run.sendPrompt(command, { ...options, signal: AbortSignal.any([this.lifetime.signal, ...(options.signal ? [options.signal] : [])]) })
+        if (acceptance.kind === 'turn' && acceptance.turnId !== this.lastEndedTurn)
+            this.activeTurn = acceptance.turnId
+        return acceptance
+    }
+
+    stop: AgentRun['stop'] = async (command, options) => {
+        if (command.sessionId !== this.metadata.sessionId || command.providerSessionId !== this.metadata.providerSessionId || command.provider !== this.metadata.provider)
+            throw new AgentRunStateError({ message: 'Stop does not target the bound run.' })
+        this.stopped = true
+        this.lifetime.abort()
+        await this.run.stop(command, options)
+        await this.dispatching?.catch(() => undefined)
+        await this.pump
+        this.events.end()
+    }
+
+    private target() {
+        return { provider: this.metadata.provider, sessionId: this.metadata.sessionId, providerSessionId: this.metadata.providerSessionId }
+    }
+
+    private async withWorkspaceChange(operation: () => Promise<void>): Promise<void> {
+        if (this.stopped)
+            throw new AgentRunStateError({ message: 'The run stopped.' })
+        if (this.dispatching || this.workspaceChanging)
+            throw new AgentPromptDeferredError({ message: 'A provider operation is already in progress.' })
+        this.workspaceChanging = true
+        try {
+            await operation()
+        }
+        finally { this.workspaceChanging = false }
+    }
+
+    private async consume(run: AgentRun, rebound = false): Promise<void> {
+        try {
+            for await (const event of run.events) {
+                if (event.type === 'turn.started' && event.actor.type === 'main')
+                    this.activeTurn = event.turnId
+                if (event.type === 'turn.ended' && event.actor.type === 'main') {
+                    this.lastEndedTurn = event.turnId
+                    if (event.turnId === this.activeTurn)
+                        this.activeTurn = undefined
+                }
+                // Internal connection teardown is not product-session completion.
+                if (this.changing && (event.type === 'session.ended' || event.type === 'session.state.changed'))
+                    continue
+                if (rebound && event.type === 'session.started')
+                    continue
+                this.emit(event)
+            }
+        }
+        catch {
+            this.stopped = true
+            this.lifetime.abort()
+            this.events.push({ type: 'error', payload: { message: 'Provider event stream failed.', fatal: true, source: 'provider' } })
+            this.events.end()
+        }
+    }
+
+    private emit(event: AgentEvent): void {
+        this.events.push(event)
+    }
+}

package/src/protocol/agent-command.ts

@@ -26,6 +26,8 @@ export const sendPromptCommandSchema = runningCommandBaseSchema.extend({
     origin: z.enum(['user', 'supervisor']).default('user'),
     prompt: agentPromptSchema,
     commandId: commandIdSchema,
+    /** Resolved by the application for this prompt, including after runtime recovery. */
+    model: z.string().trim().min(1).max(256).optional(),
     author: agentAuthorSchema.optional(),
 }).strict()
 

package/src/protocol/agent-event.ts

@@ -135,7 +135,7 @@ export const sessionEndedAgentEventSchema = agentEventBaseSchema.extend({
 
 export const turnStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('turn.started'),
-    payload: z.object({}).strict(),
+    payload: z.object({ commandId: z.string().min(1).optional() }).strict(),
 }).strict()
 
 export const turnEndedAgentEventSchema = agentTurnEventBaseSchema.extend({

package/src/provenance.gen.ts

@@ -1,6 +1,6 @@
 // Generated by scripts/write-provenance.ts. Do not edit by hand.
 export const generatedProvenance = {
-    version: "0.1.2",
-    sha: "85081b3dd3667033dfb1dfd399a6f59d3fd42d43",
-    buildTime: "2026-09-09T11:47:21.679Z",
+    version: "0.1.8",
+    sha: "ff5b7ece6b3b115d420a21046bd47b465813132b",
+    buildTime: "2026-09-10T20:15:33.140Z",
 } as const

package/src/steps/projector.ts

@@ -23,6 +23,15 @@ export class DurableStepProjector {
         this.db.exec(`pragma journal_mode=WAL; pragma synchronous=FULL;
             create table if not exists steps(id text primary key, body text not null, last_event_id text);
             create table if not exists journal(id text primary key, event text, frames text);
+            create table if not exists turn_commands(
+                session_id text not null, provider_session_id text not null,
+                actor_id text not null, turn_id text not null, command_id text not null,
+                primary key(session_id, provider_session_id, actor_id, turn_id)
+            );
+            create index if not exists steps_tool_command on steps(
+                json_extract(body,'$.sessionId'), json_extract(body,'$.actor.actorId'),
+                json_extract(body,'$.kind'), json_extract(body,'$.sourceId')
+            );
         `)
         if (!this.db.query<{ name: string }, []>('pragma table_info(steps)').all().some(column => column.name === 'last_event_id'))
             this.db.exec('alter table steps add column last_event_id text')
@@ -42,7 +51,13 @@ export class DurableStepProjector {
     }
 
     async process(event: AgentEvent, emit: (body: WireEventBody) => void): Promise<void> {
-        if (['message.delta', 'tool.output.delta', 'reasoning.summary.delta'].includes(event.type)) {
+        // Tool stdout is not assistant text. Its canonical completion carries
+        // full content to detail storage and emits only a bounded preview.
+        // Splitting stdout into small frames would still stream heavy bytes
+        // through the API and defeat the individual-details boundary.
+        if (event.type === 'tool.output.delta')
+            return
+        if (['message.delta', 'reasoning.summary.delta'].includes(event.type)) {
             // Live deltas never become historical tool payloads. Large transport
             // deltas are split rather than dropped by the supervisor frame limit.
             const body = wrapAgentEvent(event)
@@ -76,6 +91,7 @@ export class DurableStepProjector {
     }
 
     private async project(event: AgentEvent): Promise<WireEventBody[]> {
+        const commandId = this.correlateCommand(event)
         const kind = event.type.startsWith('message.')
             ? 'message'
             : event.type.startsWith('tool.call.')
@@ -86,6 +102,8 @@ export class DurableStepProjector {
             if (event.type === 'turn.ended' || event.type === 'session.ended') {
                 for (const row of this.db.query<{ body: string, last_event_id: string | null }, []>('select body, last_event_id from steps').all()) {
                     const step = JSON.parse(row.body) as StepDetailV1
+                    if (step.sessionId !== event.sessionId || step.providerSessionId !== event.providerSessionId)
+                        continue
                     if ((step.status !== 'running' && row.last_event_id !== event.eventId) || (event.type === 'turn.ended' && (step.turnId !== event.turnId || step.actor.actorId !== event.actor.actorId)))
                         continue
                     step.status = event.type === 'turn.ended' && event.payload.status === 'failed' ? 'failed' : 'interrupted'
@@ -109,7 +127,7 @@ export class DurableStepProjector {
                     stepId,
                     version: 1,
                     provider: event.provider,
-                    commandId: typeof payload.commandId === 'string' ? payload.commandId : null,
+                    commandId,
                     role: kind === 'message' ? payload.role as StepSummary['role'] : null,
                     toolName: typeof payload.toolName === 'string' ? payload.toolName : null,
                     status: 'running',
@@ -121,6 +139,7 @@ export class DurableStepProjector {
                 }
         if (step.status !== 'running' && row?.last_event_id !== event.eventId)
             return []
+        step.commandId ??= commandId
         if (event.type.endsWith('started')) {
             if (row && row.last_event_id !== event.eventId)
                 return []
@@ -158,12 +177,16 @@ export class DurableStepProjector {
     }
 
     private async finish(step: StepDetailV1): Promise<WireEventBody[]> {
+        // The provider can correlate a turn after its first content start. A
+        // terminal fact must resolve that binding too, not only normal closes.
+        step.commandId ??= this.correlateCommand(step)
         if (step.kind === 'message') {
             // References, not repeated complete tool payloads, connect message content.
-            step.content.toolSteps = this.db.query<{ id: string }, [string, string]>(`
+            step.content.toolSteps = this.db.query<{ id: string }, [string, string, string, string]>(`
                 select id from steps where json_extract(body,'$.kind')='tool'
+                and json_extract(body,'$.sessionId')=? and json_extract(body,'$.providerSessionId')=?
                 and json_extract(body,'$.turnId')=? and json_extract(body,'$.actor.actorId')=? order by rowid
-            `).all(step.turnId, step.actor.actorId).map(row => row.id)
+            `).all(step.sessionId, step.providerSessionId, step.turnId, step.actor.actorId).map(row => row.id)
         }
         this.save(step)
         const body = serializeStepDetail(step)
@@ -179,6 +202,39 @@ export class DurableStepProjector {
         ]
     }
 
+    private correlateCommand(event: AgentEvent | StepDetailV1): string | null {
+        if (!('turnId' in event))
+            return null
+        const key = [event.sessionId, event.providerSessionId, event.actor.actorId, event.turnId] as const
+        const previous = this.db.query<{ command_id: string }, [string, string, string, string]>(
+            'select command_id from turn_commands where session_id=? and provider_session_id=? and actor_id=? and turn_id=?',
+        ).get(...key)?.command_id
+        const payload = 'payload' in event ? event.payload as Record<string, unknown> : event
+        const explicit = typeof payload.commandId === 'string' ? payload.commandId : undefined
+        if (previous && explicit && previous !== explicit)
+            throw new Error('Conflicting command identity for a provider turn.')
+        let inherited: string | undefined
+        if (!previous && !explicit && event.actor.type === 'subagent') {
+            const toolCallId = event.actor.parentToolCallId
+                ?? (event.actor.origin.type === 'tool_call' ? event.actor.origin.toolCallId : undefined)
+            if (toolCallId) {
+                const parents = this.db.query<{ command_id: string }, [string, string, string]>(`
+                    select distinct json_extract(body,'$.commandId') as command_id from steps
+                    where json_extract(body,'$.sessionId')=? and json_extract(body,'$.actor.actorId')=?
+                    and json_extract(body,'$.kind')='tool' and json_extract(body,'$.sourceId')=?
+                    and json_extract(body,'$.commandId') is not null limit 2
+                `).all(event.sessionId, event.actor.parentActorId, toolCallId)
+                if (parents.length === 1)
+                    inherited = parents[0]!.command_id
+            }
+        }
+        const commandId = previous ?? explicit ?? inherited
+        if (commandId && !previous) {
+            this.db.query('insert into turn_commands values (?,?,?,?,?)').run(...key, commandId)
+        }
+        return commandId ?? null
+    }
+
     private save(step: StepDetailV1): void {
         this.db.query('insert into steps(id,body,last_event_id) values (?,?,?) on conflict(id) do update set body=excluded.body,last_event_id=excluded.last_event_id')
             .run(step.stepId, JSON.stringify(step), this.currentEventId)

package/src/supervisor/agent-provider-factory.ts

@@ -128,6 +128,7 @@ class AgentSupervisorRuntime implements SupervisorAgentRuntime {
                 providerSessionId: metadata.providerSessionId,
                 commandId: input.commandId,
                 mode: input.body.mode,
+                model: input.body.model,
                 origin: 'user',
                 prompt: input.body.prompt,
                 author: input.body.user

package/src/supervisor-protocol/command-body.ts

@@ -40,6 +40,7 @@ export const wireCommandExtensionsSchema = jsonObjectSchema.refine(
 const wireSendPromptCommandSchema = z.object({
     type: z.literal('agent.send-prompt'),
     mode: agentPromptModeSchema,
+    model: z.string().trim().min(1).max(256).optional(),
     prompt: agentPromptSchema,
     attachments: z.array(wireInputAttachmentRefSchema).superRefine((attachments, context) => {
         const attachmentIds = new Set<string>()