@meistrari/agent-core 0.2.0-experimental.6 → 0.2.0-experimental.8

package/README.md

@@ -149,3 +149,10 @@ bypass-permissions mode as root, so run them as a regular user.
 Regenerate the experimental Codex wire types with `bun run generate:codex-protocol`.
 The generator pins Codex 0.159.0 and verifies any `CODEX_EXECUTABLE` override before
 using it. Commit generated files with generator changes; CI checks reproducibility.
+
+
+## Standalone settings changes
+
+`agent.change-settings` carries a full `settings: { model, reasoningEffort }` pair through the supervisor wire and the agent protocol. Claude and Codex apply it only at an idle turn boundary, without submitting input, and emit `session.settings.changed` with the command ID and `appliesFrom: next_turn`. Product catalog, provider compatibility and admission ordering remain the caller's responsibility.
+
+The supervisor advertises `capabilities["model-change"] = "v1"` in health. It commits the settings command outcome and inbox status in one SQLite transaction. After a process restart, an interrupted settings command can be reapplied idempotently; prompt commands retain their uncertain-delivery policy and are never retried by this path. Confirmed settings override the immutable bootstrap defaults when resuming the provider. Prompt and user-input-answer commands may carry resolved `settings` so their execution does not rely solely on mutable defaults.

package/docs/model-effort-changes.md

@@ -0,0 +1,60 @@
+# Model and reasoning effort changes
+
+agent-core can update a session's model and reasoning effort without sending a
+conversational prompt. Healthy Claude and Codex sessions keep the same CLI process
+and provider session, preserving their warmed runtime state.
+
+![Claude and Codex live model and effort updates](diagrams/model-effort-change.png)
+
+## Standalone command
+
+Send `agent.change-settings` with `settings: { model, reasoningEffort }` at an idle
+turn boundary. The caller schedules that boundary; a busy run defers the operation.
+
+The supervisor persists the command in its inbox and acknowledges receipt with
+`command.ack`. Receipt does not mean the provider has applied the settings.
+
+| Provider | How settings are applied | Acceptance |
+| --- | --- | --- |
+| Claude | `query.setModel(model)` and `query.applyFlagSettings({ effortLevel })`, skipping unchanged known values | The required control responses succeed |
+| Codex | `thread/settings/update` with `{ threadId, model, effort }` | The JSON-RPC request succeeds |
+
+After acceptance, the run updates its defaults and emits `session.settings.changed`
+with `model`, `reasoningEffort`, the initiating `commandId`, and
+`appliesFrom: 'next_turn'`. The supervisor commits the accepted settings together
+with command completion, then sends `supervisor.command.applied`.
+
+A provider failure does not produce a successful settings-change event or a
+successful command completion. Receipt alone must never update a consumer's
+display of confirmed settings.
+
+## Settings carried by inputs
+
+`agent.send-prompt.settings` and `agent.respond-user-input.settings` can carry
+partial settings. Omitted fields retain the currently accepted values. Prompt
+settings retain the provider's `next` and `steer` behavior; the confirmation event
+identifies whether the change applies to the current or next turn. Already-delivered
+answers do not change defaults or emit another settings-change event.
+
+For prompts, a supplied `settings` object takes precedence over the entire legacy
+top-level `model` / `reasoningEffort` pair, even when the object is empty. Without
+that object, accepted legacy fields are also persisted as default changes. Missing
+legacy fields do not clear previously accepted defaults.
+
+Claude's legacy top-level effort field must match the current accepted effort.
+Use `settings.reasoningEffort` or the standalone command to change it. For example,
+after starting at `medium` and successfully applying standalone `high`, a legacy
+prompt specifying `high` is accepted; one specifying `medium` is rejected.
+
+## Recovery
+
+The supervisor restores the latest accepted defaults across standalone commands,
+prompts, and answers. For example, standalone A/high, followed by a legacy prompt
+B/low, followed by `settings: { reasoningEffort: 'medium' }`, recovers as B/medium.
+Failed commands and already-delivered answers do not replace those defaults.
+
+The Bedrock wrapper retains its legacy prompt model-rebinding path. Standalone
+changes bypass that path on a healthy connection. If a previous replacement failed
+and left the old run stopped, the wrapper first recovers a connection with its
+previously accepted settings, then applies the requested update. Recovery preserves
+the provider session identity and does not replay the failed prompt.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@meistrari/agent-core",
     "type": "module",
-    "version": "0.2.0-experimental.6",
+    "version": "0.2.0-experimental.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/src/agents/agent-run.ts

@@ -3,6 +3,7 @@ import type {
     AgentEvent,
     AgentNotifyCommand,
     AgentRunMetadata,
+    ChangeSettingsAgentCommand,
     CompactContextAgentCommand,
     InterruptAgentCommand,
     RespondUserInputAgentCommand,
@@ -34,6 +35,7 @@ export interface AgentRun {
     prepareWorkspace: (options?: AgentOperationOptions) => Promise<void>
     // Providers without root registration accept the root without provider I/O.
     addWorkspaceRepositoryRoot: (root: string, options?: AgentOperationOptions) => Promise<void>
+    changeSettings?: (command: ChangeSettingsAgentCommand, options?: AgentOperationOptions) => Promise<void>
     sendPrompt: (command: SendPromptCommand, options?: AgentPromptOperationOptions) => Promise<AgentPromptAcceptance>
     // Optional capabilities: the Claude and Codex runs implement both; other runs may omit them.
     notify?: (command: AgentNotifyCommand, options?: AgentOperationOptions) => Promise<AgentNotificationAcceptance>

package/src/agents/claude/claude-code-process.ts

@@ -25,7 +25,7 @@ export class ClaudeCodeProcess {
     private termination: Promise<void> | undefined
     private stderr = ''
 
-    constructor(private readonly exitTimeoutMs = CLAUDE_PROCESS_EXIT_TIMEOUT_MS) {}
+    constructor(private readonly exitTimeoutMs = CLAUDE_PROCESS_EXIT_TIMEOUT_MS, private readonly processLauncher?: string) {}
 
     /** The SDK `spawnClaudeCodeProcess` hook. A run spawns at most one process. */
     readonly spawn = (options: SpawnOptions): SpawnedProcess => {
@@ -33,10 +33,10 @@ export class ClaudeCodeProcess {
             throw new Error('Claude Code process already spawned for this run.')
         // `detached` makes the CLI a process-group leader. The forwarded signal aborts only after the
         // SDK's graceful stdin-EOF window, as for the SDK's own spawn.
-        const child = spawn(options.command, options.args, { cwd: options.cwd, env: options.env, signal: options.signal, stdio: ['pipe', 'pipe', 'pipe'], detached: true, windowsHide: true })
+        const child = spawn(this.processLauncher ?? options.command, this.processLauncher ? [options.command, ...options.args] : options.args, { cwd: options.cwd, env: options.env, signal: options.signal, stdio: ['pipe', 'pipe', 'pipe'], detached: true, windowsHide: true })
         this.child = child
         this.exit = new Promise((resolve) => {
-            child.once('exit', () => resolve())
+            child.once(this.processLauncher ? 'close' : 'exit', () => resolve())
             // A failed spawn emits `error` without `exit`; there is no process to wait for.
             child.once('error', () => {
                 if (child.pid === undefined)
@@ -70,15 +70,21 @@ export class ClaudeCodeProcess {
         const exit = this.exit
         if (!child || !exit || child.pid === undefined)
             return
-        if (await settlesWithin(exit, this.exitTimeoutMs))
+        // A fork/wait launcher can exit while its CLI still holds the stdio pipes.
+        // For launchers, await close and clean the group even if the wrapper already exited.
+        if (await settlesWithin(exit, this.exitTimeoutMs) && !this.processLauncher)
             return
         try {
             process.kill(-child.pid, 'SIGKILL')
         }
-        catch {
+        catch (error) {
+            if (this.processLauncher && process.platform !== 'win32' && (error as NodeJS.ErrnoException).code !== 'ESRCH')
+                throw error
             child.kill('SIGKILL')
         }
-        await settlesWithin(exit, killedExitWaitMs)
+        const closed = await settlesWithin(exit, killedExitWaitMs)
+        if (this.processLauncher && !closed)
+            throw new Error('Claude launcher process group did not close after SIGKILL.')
     }
 }
 

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

@@ -71,6 +71,14 @@ export interface ClaudeProviderConfig {
     desktop?: ClaudeDesktopConfig | null
     tools?: readonly AgentTool[]
     executable?: string
+    /**
+     * Trusted launcher invoked as <CLI executable> <CLI args>; owns any privilege drop.
+     * Preserve stdio and the process group: exec the CLI or keep children in that group.
+     * On Windows, the launcher must exec the CLI in place (group signals are unavailable).
+     */
+    processLauncher?: string
+    /** Private provider stores; defaults to the CLI transcript directory when omitted. */
+    runtimeStateRoot?: string
     environment?: Record<string, string | undefined>
     nativeToolActorBridge?: ClaudeNativeToolActorBridge
     startupDeadlineMs?: number
@@ -139,6 +147,8 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
     private readonly desktop: ClaudeDesktopConfig | null
     private readonly tools: readonly AgentTool[]
     private readonly executable: string | undefined
+    private readonly processLauncher: string | undefined
+    private readonly runtimeStateRoot: string | undefined
     private readonly environment: Record<string, string | undefined>
     private readonly nativeToolActorBridge: ClaudeNativeToolActorBridge | undefined
     private readonly startupDeadlineMs: number
@@ -156,6 +166,8 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
         this.desktop = config.desktop ?? null
         this.tools = config.tools ?? []
         this.executable = config.executable
+        this.processLauncher = config.processLauncher
+        this.runtimeStateRoot = config.runtimeStateRoot
         this.environment = config.environment ?? {}
         this.nativeToolActorBridge = config.nativeToolActorBridge
         this.startupDeadlineMs = config.startupDeadlineMs ?? CLAUDE_STARTUP_DEADLINE_MS
@@ -202,10 +214,10 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
         const runtime = createClaudeToolRuntimeRef({ turnId: () => state.currentTurnId })
         // The transcript location is a pre-input fact; session-local stores live beside it.
         const transcriptPath = join(configDir, 'projects', encodeClaudeProjectPath(input.cwd), `${expectedSessionId}.jsonl`)
-        const steeredNotifications = ClaudeSteeredNotificationStore.open({ sessionId: input.sessionId, transcriptPath })
+        const steeredNotifications = ClaudeSteeredNotificationStore.open({ sessionId: input.sessionId, transcriptPath, rootDir: this.runtimeStateRoot })
         const resources = await this.openRunResources({ input, expectedSessionId, signal: abortController.signal })
         const { nativeToolActorRun, workspaceSkills, selectedRepositoryInstructions, browserAuthBroker, browserTurnMetadata } = resources
-        const claudeProcess = new ClaudeCodeProcess()
+        const claudeProcess = new ClaudeCodeProcess(undefined, this.processLauncher)
         const declaredSubscriptionType = this.auth ? fetchFreeSubscriptionType(this.auth.knownSubscriptionType()) : undefined
         const runtimeMcpServers = toClaudeMcpServers({
             tools,
@@ -302,7 +314,7 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
             const [userInputRequests, initialization, , sessionContext] = await Promise.all([
                 UserInputRequestStore.open({
                     sessionId: metadata.sessionId,
-                    rootDir: userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
+                    rootDir: this.runtimeStateRoot ?? userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
                 }),
                 awaitClaudeInitialization({ query, signal: abortController.signal, deadlineMs: this.startupDeadlineMs }),
                 this.auth?.acquire({ signal: abortController.signal }),
@@ -314,8 +326,12 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
             if (this.auth && declaredSubscriptionType !== undefined && declaredSubscriptionType !== fetchFreeSubscriptionType(this.auth.knownSubscriptionType()) && !params.respawnedForSubscriptionType) {
                 query.close()
                 inputQueue.close()
-                await claudeProcess.terminate()
-                await closeRunResources(resources)
+                try {
+                    await claudeProcess.terminate()
+                }
+                finally {
+                    await closeRunResources(resources)
+                }
                 return await this.openRun({ ...params, respawnedForSubscriptionType: true })
             }
 
@@ -372,8 +388,12 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
             query.close()
             inputQueue.close()
             // A failed open (for example a missed initialize deadline) must not leave its CLI behind.
-            await claudeProcess.terminate()
-            await closeRunResources(resources)
+            try {
+                await claudeProcess.terminate()
+            }
+            finally {
+                await closeRunResources(resources)
+            }
             throw error
         }
     }

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

@@ -1,18 +1,6 @@
 import type { Query, SDKMessage, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk'
 import type { UUID } from 'node:crypto'
-import type {
-    AgentContextCompactionRequestResult,
-    AgentError,
-    AgentNotifyCommand,
-    AgentReasoningEffort,
-    AgentRunMetadata,
-    AgentSettingsChange,
-    CompactContextAgentCommand,
-    InterruptAgentCommand,
-    RespondUserInputAgentCommand,
-    SendPromptCommand,
-    StopAgentCommand,
-} from '../../protocol'
+import type { AgentContextCompactionRequestResult, AgentError, AgentNotifyCommand, AgentReasoningEffort, AgentRunMetadata, AgentSettingsChange, ChangeSettingsAgentCommand, CompactContextAgentCommand, InterruptAgentCommand, RespondUserInputAgentCommand, SendPromptCommand, StopAgentCommand } from '../../protocol'
 import type { AgentEventDraft } from '../agent-event-stream'
 import type { AgentOperationOptions, AgentPromptOperationOptions } from '../agent-operation'
 import type { AgentNotificationAcceptance, AgentPromptAcceptance, AgentRun, AgentUserInputSubmission } from '../agent-run'
@@ -297,6 +285,10 @@ export class ClaudeRun implements AgentRun {
         this.events.push(decorated)
         if (draft.type === 'turn.started' && draft.payload.commandId)
             this.emitAcceptedMessage(draft.payload.commandId, draft.turnId)
+        // Running may precede the input's started receipt. Consumption identifies the turn
+        // after that receipt, before the mapper emits the assistant's message.
+        if (draft.type === 'prompt.turn-correlated')
+            this.emitAcceptedMessage(draft.payload.commandId, draft.payload.turnId)
     }
 
     // The accepted input becomes a user message of the turn that consumed it, correlated with the
@@ -356,6 +348,28 @@ export class ClaudeRun implements AgentRun {
         this.skillReloadOwed = false
     }
 
+    async changeSettings(command: ChangeSettingsAgentCommand, options: AgentOperationOptions = {}): Promise<void> {
+        this.assertCommandTargetsRun(command)
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        if (this.eventMapperState.currentTurnId || this.commandByClientMessageId.size > 0 || this.modelChangeInFlight)
+            throw new AgentPromptDeferredError({ message: 'Settings changes require an idle turn boundary.' })
+        this.modelChangeInFlight = true
+        try {
+            const settings = this.settingsWith(command.settings)
+            await this.applyProviderSettings(settings)
+            this.current = settings
+            if (settings.model) {
+                this.metadata.model = settings.model
+                this.init.requestedModel = settings.model
+            }
+            this.pushEvent(sessionSettingsChangedEvent({ model: settings.model!, reasoningEffort: settings.effort, commandId: command.commandId, appliesFrom: 'next_turn' }))
+        }
+        finally {
+            this.modelChangeInFlight = false
+        }
+    }
+
     async sendPrompt(command: SendPromptCommand, options: AgentPromptOperationOptions = {}): Promise<AgentPromptAcceptance> {
         this.assertCommandTargetsRun(command)
         this.assertRunning()
@@ -365,7 +379,7 @@ export class ClaudeRun implements AgentRun {
                 message: 'Bypass submission requires a steer prompt.',
             })
         }
-        if (command.reasoningEffort !== undefined && command.reasoningEffort !== this.init.reasoningEffort)
+        if (!command.settings && command.reasoningEffort !== undefined && command.reasoningEffort !== this.current.effort)
             throw new AgentNotAcceptedError({ message: 'Claude reasoning effort changes are not supported by this adapter.', recovery: { kind: 'terminal', reason: 'reasoning_effort_change_not_supported' } })
         // Claude Code steers by cancelling the running ask, which would abort a manual compaction
         // (CLI 2.1.280). Like Codex's non-steerable compaction turn, the steer waits for it to end.
@@ -441,6 +455,8 @@ export class ClaudeRun implements AgentRun {
     private async applyCommandModel(command: SendPromptCommand, options: AgentOperationOptions): Promise<void> {
         if (this.modelChangeInFlight)
             throw new AgentPromptDeferredError({ message: 'Claude model configuration is still in progress.' })
+        if (command.settings)
+            return
         const currentModel = this.init.requestedModel ?? this.metadata.model
         if (!command.model || command.model === currentModel)
             return
@@ -742,7 +758,8 @@ export class ClaudeRun implements AgentRun {
             return 'already_delivered'
         // Deliver first: on a prebound resume this is the run's first input, and the resolved
         // event must not precede the lifecycle events the init barrier emits.
-        await this.applyProviderSettings(this.current)
+        const settings = this.settingsWith(command.settings)
+        await this.applyProviderSettings(settings)
         // The answer opens its turn as the user's input, correlated like a prompt: the turn it
         // starts carries this command, and the answer is accepted as that turn's user message.
         const clientMessageId = deriveMessageId(command.commandId)
@@ -762,6 +779,16 @@ export class ClaudeRun implements AgentRun {
         finally {
             this.acceptanceWaiters.delete(clientMessageId)
         }
+        if (command.settings) {
+            this.current = settings
+            this.pushEvent(sessionSettingsChangedEvent({
+                model: settings.model ?? await this.initialization,
+                reasoningEffort: settings.effort,
+                commandId: command.commandId,
+                turnId: this.eventMapperState.currentTurnId,
+                appliesFrom: 'current_turn',
+            }))
+        }
         if (resolved.event)
             this.pushEvent(resolved.event)
         this.userInputRequests.markDelivered(command.requestId)
@@ -879,18 +906,31 @@ export class ClaudeRun implements AgentRun {
             cause: error,
         }))
         this.ended = this.endAfterProcessExit(reason, error)
+        // Autonomous stream failure may finish without a stop caller; keep rejection observed.
+        void this.ended.catch(() => undefined)
     }
 
-    // session.ended means the CLI is gone: the terminal events wait for its exit (bounded by
+    // A successful session.ended means the CLI is gone: the terminal events wait for its exit (bounded by
     // CLAUDE_PROCESS_EXIT_TIMEOUT_MS, then a process-group kill). close() is idempotent and sends
     // the stdin EOF the CLI exits on.
     private async endAfterProcessExit(reason: 'completed' | 'stopped' | 'interrupted' | 'failed', error: AgentError | undefined): Promise<void> {
         this.closeQuery()
-        await this.process.terminate()
-        this.events.push({ type: 'session.ended', payload: error ? { reason, error } : { reason } })
-        this.events.push({ type: 'session.state.changed', payload: { state: reason === 'failed' ? 'failed' : 'stopped' } })
-        this.events.end()
-        void this.onFinished().catch(() => undefined)
+        try {
+            await this.process.terminate()
+            this.events.push({ type: 'session.ended', payload: error ? { reason, error } : { reason } })
+            this.events.push({ type: 'session.state.changed', payload: { state: reason === 'failed' ? 'failed' : 'stopped' } })
+        }
+        catch (cause) {
+            const shutdownError = { ...serializeAgentError(cause), code: 'agents.provider-shutdown-failed' }
+            this.events.push({ type: 'error', payload: { message: 'Claude CLI shutdown could not be confirmed.', fatal: true, source: 'runtime', error: shutdownError } })
+            this.events.push({ type: 'session.ended', payload: { reason: 'failed', error: shutdownError } })
+            this.events.push({ type: 'session.state.changed', payload: { state: 'failed' } })
+            throw cause
+        }
+        finally {
+            this.events.end()
+            await this.onFinished().catch(() => undefined)
+        }
     }
 
     // Reports the request's one result; later calls return the reported one. The caller decides

package/src/agents/claude/claude-steered-notifications.ts

@@ -48,9 +48,9 @@ export interface SteeredNotificationDelivery {
 export class ClaudeSteeredNotificationStore {
     private constructor(private readonly filePath: string, private file: StoreFile) {}
 
-    static open(input: { sessionId: string, transcriptPath: string }): ClaudeSteeredNotificationStore {
+    static open(input: { sessionId: string, transcriptPath: string, rootDir?: string }): ClaudeSteeredNotificationStore {
         const filePath = join(
-            dirname(input.transcriptPath),
+            input.rootDir ?? dirname(input.transcriptPath),
             storeDirectoryName,
             Buffer.from(input.sessionId, 'utf8').toString('base64url'),
             storeFileName,

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

@@ -59,7 +59,9 @@ export class CodexJsonRpcClient {
     readonly child: ChildProcessWithoutNullStreams
     private nextId = 0
     private stopped = false
+    private shutdown: Promise<void> | undefined
     private readonly closed: Promise<void>
+    private readonly processGroup: boolean
     private readonly pending = new Map<string, {
         method: ClientRequestMethod
         resolve: (value: unknown) => void
@@ -70,6 +72,7 @@ export class CodexJsonRpcClient {
         executable: string,
         options: {
             cwd: string
+            processLauncher?: string
             environment?: Record<string, string | undefined>
             configOverrides?: readonly string[]
             onMessage: (message: CodexJsonRpcMessage) => void
@@ -78,10 +81,13 @@ export class CodexJsonRpcClient {
             maxLineBytes?: number
         },
     ) {
-        this.child = spawn(executable, ['app-server', '--listen', 'stdio://', ...(options.configOverrides ?? []).flatMap(value => ['-c', value])], {
+        this.processGroup = options.processLauncher !== undefined && process.platform !== 'win32'
+        const args = ['app-server', '--listen', 'stdio://', ...(options.configOverrides ?? []).flatMap(value => ['-c', value])]
+        this.child = spawn(options.processLauncher ?? executable, options.processLauncher ? [executable, ...args] : args, {
             cwd: options.cwd,
             env: options.environment,
             stdio: 'pipe',
+            detached: this.processGroup,
         })
         this.closed = new Promise(resolve => this.child.once('close', () => resolve()))
 
@@ -229,9 +235,16 @@ export class CodexJsonRpcClient {
     }
 
     async closeInputAndStop(): Promise<void> {
+        this.shutdown ??= this.drainAndStop()
+        await this.shutdown
+    }
+
+    private async drainAndStop(): Promise<void> {
         if (this.stopped) {
             if (!await waitForClosed(this.closed, PROCESS_SHUTDOWN_GRACE_MS))
-                await terminateChild(this.child, this.closed)
+                await terminateChild(this.child, this.closed, this.processGroup)
+            if (this.processGroup)
+                signalProcessGroup(this.child, 'SIGKILL')
             return
         }
         this.stopped = true
@@ -242,9 +255,10 @@ export class CodexJsonRpcClient {
         // EOF/drain and process exit share one grace window. Never wait separately for a
         // buffered stdin write: a child that stops reading must still reach signal escalation.
         this.child.stdin.end()
-        if (await waitForClosed(this.closed, PROCESS_SHUTDOWN_GRACE_MS))
-            return
-        await terminateChild(this.child, this.closed)
+        if (!await waitForClosed(this.closed, PROCESS_SHUTDOWN_GRACE_MS))
+            await terminateChild(this.child, this.closed, this.processGroup)
+        if (this.processGroup)
+            signalProcessGroup(this.child, 'SIGKILL')
     }
 
     async stop(): Promise<void> {
@@ -288,7 +302,17 @@ export class CodexJsonRpcClient {
     }
 }
 
-async function terminateChild(child: ChildProcessWithoutNullStreams, closed: Promise<void>): Promise<void> {
+async function terminateChild(child: ChildProcessWithoutNullStreams, closed: Promise<void>, processGroup: boolean): Promise<void> {
+    if (processGroup) {
+        // The launcher may already be gone while the CLI retains its pipes. Signal the
+        // retained group regardless of the wrapper's exitCode, and bound the close wait.
+        for (const signal of ['SIGINT', 'SIGTERM', 'SIGKILL'] as const) {
+            signalProcessGroup(child, signal)
+            if (await waitForClosed(closed, signal === 'SIGKILL' ? 1_000 : PROCESS_SHUTDOWN_GRACE_MS))
+                return
+        }
+        throw new Error('Codex launcher process group did not close after SIGKILL.')
+    }
     if (child.exitCode !== null || child.signalCode !== null) {
         await closed
         return
@@ -308,6 +332,18 @@ async function terminateChild(child: ChildProcessWithoutNullStreams, closed: Pro
     await closed
 }
 
+function signalProcessGroup(child: ChildProcessWithoutNullStreams, signal: NodeJS.Signals): void {
+    if (child.pid === undefined)
+        return
+    try {
+        process.kill(-child.pid, signal)
+    }
+    catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ESRCH')
+            throw error
+    }
+}
+
 async function waitForClosed(closed: Promise<void>, timeoutMs: number): Promise<boolean> {
     return await new Promise<boolean>((resolve) => {
         const timer = setTimeout(() => resolve(false), timeoutMs)

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

@@ -54,6 +54,14 @@ export interface CodexProviderConfig {
     auth: CodexAuthProvider | CodexAuthentication
     tools?: readonly AgentTool[]
     executable?: string
+    /**
+     * Trusted launcher invoked as <CLI executable> <CLI args>; owns any privilege drop.
+     * Preserve stdio and the process group: exec the CLI or keep children in that group.
+     * On Windows, the launcher must exec the CLI in place (group signals are unavailable).
+     */
+    processLauncher?: string
+    /** Private provider stores; defaults to the CLI transcript directory when omitted. */
+    runtimeStateRoot?: string
     environment?: Record<string, string | undefined>
     onStartupStage?: (fact: CodexStartupStageFact) => void
     instructions?: InstructionComposer
@@ -111,6 +119,8 @@ export class CodexProvider implements AgentProvider<'codex'> {
     private readonly tools: readonly AgentTool[]
     private readonly executable: string
     private readonly environment: Record<string, string | undefined>
+    private readonly processLauncher: string | undefined
+    private readonly runtimeStateRoot: string | undefined
     private readonly auth: CodexAuthentication
     /** The validated endpoint of an API key login that names one. */
     private readonly apiKeyEndpoint: string | undefined
@@ -130,6 +140,8 @@ export class CodexProvider implements AgentProvider<'codex'> {
         this.tools = config.tools ?? []
         this.executable = config.executable ?? 'codex'
         this.environment = config.environment ?? {}
+        this.processLauncher = config.processLauncher
+        this.runtimeStateRoot = config.runtimeStateRoot
         this.onStartupStage = config.onStartupStage
         this.instructions = config.instructions ?? emptyInstructionComposer
         this.sessionContext = config.sessionContext
@@ -169,18 +181,19 @@ export class CodexProvider implements AgentProvider<'codex'> {
         return this.wrapBedrockRun(await this.resumeRawSession(input, options), input)
     }
 
-    // Bedrock model bindings are fixed per app-server session, so a model change resumes the same
-    // thread under the new binding at an idle turn boundary.
+    // Legacy prompt-only model changes rebind at an idle boundary. Explicit settings
+    // commands use the native update on the existing thread and keep the CLI warm.
     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({
+        return new ModelRebindingRun(run, async (model, signal, reasoningEffort) => await this.resumeRawSession({
             ...input,
             model: codexModelIdSchema.parse(model),
+            reasoningEffort,
             providerSessionId: run.metadata.providerSessionId,
             workspaceRepositoryRoots: [...roots],
-        }, { signal }), root => roots.add(root))
+        }, { signal }), root => roots.add(root), input.reasoningEffort)
     }
 
     private async resumeRawSession(input: AgentSessionResumeInput<'codex'>, options: AgentOperationOptions = {}): Promise<CodexRun> {
@@ -458,6 +471,7 @@ export class CodexProvider implements AgentProvider<'codex'> {
 
         try {
             client = new CodexJsonRpcClient(this.executable, {
+                processLauncher: this.processLauncher,
                 cwd,
                 environment: holder.browserAuthBroker
                     ? { ...this.environment, CODING_AGENT_BROWSER_AUTH_SOCKET: holder.browserAuthBroker.socketPath }
@@ -637,7 +651,7 @@ export class CodexProvider implements AgentProvider<'codex'> {
             }),
             UserInputRequestStore.open({
                 sessionId: metadata.sessionId,
-                rootDir: userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
+                rootDir: this.runtimeStateRoot ?? userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
             }),
             pendingSessionContext({
                 compose: this.sessionContext,

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

@@ -1,17 +1,4 @@
-import type {
-    AgentAuthor,
-    AgentContextCompactionRequestResult,
-    AgentNotifyCommand,
-    AgentPrompt,
-    AgentReasoningEffort,
-    AgentRunMetadata,
-    AgentSettingsChange,
-    CompactContextAgentCommand,
-    InterruptAgentCommand,
-    RespondUserInputAgentCommand,
-    SendPromptCommand,
-    StopAgentCommand,
-} from '../../protocol'
+import type { AgentAuthor, AgentContextCompactionRequestResult, AgentNotifyCommand, AgentPrompt, AgentReasoningEffort, AgentRunMetadata, AgentSettingsChange, ChangeSettingsAgentCommand, CompactContextAgentCommand, InterruptAgentCommand, RespondUserInputAgentCommand, SendPromptCommand, StopAgentCommand } from '../../protocol'
 import type { AgentEventDraft } from '../agent-event-stream'
 import type { AgentOperationOptions, AgentPromptOperationOptions } from '../agent-operation'
 import type { AgentNotificationAcceptance, AgentPromptAcceptance, AgentRun, AgentUserInputSubmission } from '../agent-run'
@@ -21,6 +8,7 @@ import type { CodexEventMapperState } from './codex-event-mapper'
 import type { CodexJsonRpcClient } from './codex-json-rpc-client'
 import type { ClientRequestResponsesByMethod, CodexUserInput } from './codex-protocol'
 import { serializeAgentNotificationToolOutput } from '../../protocol'
+import { serializeAgentError } from '../agent-error-serializer'
 import { AgentEventStream } from '../agent-event-stream'
 import { AgentDeliveryUnknownError, AgentNotAcceptedError, AgentPromptDeferredError, AgentRunStateError } from '../agent-runtime-error'
 import { sessionSettingsChangedEvent } from '../agent-session-events'
@@ -146,7 +134,7 @@ export class CodexRun implements AgentRun {
             sessionId: this.metadata.sessionId,
             providerSessionId: this.metadata.providerSessionId,
             reason: 'aborted',
-        }))
+        }).catch(() => undefined))
     }
 
     pushEvent(draft: AgentEventDraft): void {
@@ -273,6 +261,22 @@ export class CodexRun implements AgentRun {
         await stopping.promise
     }
 
+    async changeSettings(command: ChangeSettingsAgentCommand, options: AgentOperationOptions = {}): Promise<void> {
+        this.assertCommandTargetsRun(command)
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        this.deferNextWhileTurnActive('next')
+        const settings = withSettingsChange(this.current, command.settings)
+        try {
+            await this.client.request('thread/settings/update', { threadId: this.metadata.providerSessionId, model: this.resolveInferenceModel(settings.model), effort: codexEffort(settings.effort) })
+        }
+        catch (error) {
+            throw mapSettingsTransportLoss(error)
+        }
+        this.metadata.model = settings.model
+        this.settingsAccepted({ settings, commandId: command.commandId, turnId: undefined, placement: { appliesFrom: 'next_turn' } })
+    }
+
     async sendPrompt(command: SendPromptCommand, options: AgentPromptOperationOptions = {}): Promise<AgentPromptAcceptance> {
         this.assertCommandTargetsRun(command)
         this.assertRunning()
@@ -582,11 +586,14 @@ 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.startTurn({
+        const settings = withSettingsChange(this.current, command.settings)
+        const { receipt } = await this.startTurn({
             commandId: prepared.commandId,
-            settings: this.current,
+            settings,
             content: { kind: 'prompt', input: prepared.input, origin: prepared.origin },
         }, options)
+        if (command.settings)
+            this.settingsAccepted({ settings, commandId: command.commandId, turnId: receipt.turnId, placement: { appliesFrom: 'current_turn' } })
         this.sessionContextDelivered(prepared.sessionContext)
         this.userInputRequests.markDelivered(command.requestId)
         return 'submitted'
@@ -639,8 +646,20 @@ export class CodexRun implements AgentRun {
         const revocation = new Promise<void>((resolve) => {
             resolve(this.onStop())
         })
-        void Promise.all([this.client.stop(), revocation])
-            .then(finalize)
+        void Promise.allSettled([this.client.stop(), revocation])
+            .then((outcomes) => {
+                const failure = outcomes.find(outcome => outcome.status === 'rejected')
+                if (!failure) {
+                    finalize()
+                    return
+                }
+                const error = { ...serializeAgentError(failure.reason), code: 'agents.provider-shutdown-failed' }
+                this.events.push({ type: 'error', payload: { message: 'Codex run shutdown could not be confirmed.', fatal: true, source: 'runtime', error } })
+                this.events.push({ type: 'session.ended', payload: { reason: 'failed', error } })
+                this.events.push({ type: 'session.state.changed', payload: { state: 'failed' } })
+                this.events.end()
+                throw failure.reason
+            })
             .then(stopping.resolve, stopping.reject)
     }
 

package/src/agents/input-attachment-preparation.ts

@@ -1,5 +1,5 @@
-import type { Buffer } from 'node:buffer'
 import type { MaterializedAgentInputAttachment } from './materialized-input-attachment'
+import { Buffer } from 'node:buffer'
 import { readFile } from 'node:fs/promises'
 import { AgentInputAttachmentPreparationFailure } from './input-attachment.errors'
 
@@ -8,7 +8,9 @@ type NativeImageMimeType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/web
 export async function readAttachmentBytes(attachment: MaterializedAgentInputAttachment, signal: AbortSignal): Promise<Buffer> {
     signal.throwIfAborted()
     try {
-        const bytes = await readFile(attachment.localPath, { signal })
+        const bytes = attachment.readBytes
+            ? Buffer.from(await attachment.readBytes(signal))
+            : await readFile(attachment.localPath, { signal })
         signal.throwIfAborted()
         return bytes
     }

package/src/agents/materialized-input-attachment.ts

@@ -6,6 +6,8 @@ export type MaterializedAgentInputAttachment = Readonly<{
     byteSize: number
     sha256: string
     localPath: string
+    /** Read as the file owner when the provider uses a different process identity. */
+    readBytes?: (signal: AbortSignal) => Promise<Uint8Array>
 }>
 
 export type AgentInputAttachmentProjection = Readonly<{

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

@@ -1,4 +1,4 @@
-import type { AgentEvent, AgentRunMetadata, SendPromptCommand } from '../protocol'
+import type { AgentEvent, AgentReasoningEffort, AgentRunMetadata, ChangeSettingsAgentCommand, SendPromptCommand } from '../protocol'
 import type { AgentOperationOptions, AgentPromptOperationOptions } from './agent-operation'
 import type { AgentPromptAcceptance, AgentRun } from './agent-run'
 import { AgentEventStream } from './agent-event-stream'
@@ -12,7 +12,8 @@ export class ModelRebindingRun implements AgentRun {
     private pump: Promise<void>
     private activeTurn: string | undefined
     private lastEndedTurn: string | undefined
-    private dispatching: Promise<AgentPromptAcceptance> | undefined
+    private dispatching: Promise<unknown> | undefined
+    private settingsChanging = false
     private changing = false
     private needsRebind = false
     private stopped = false
@@ -21,7 +22,7 @@ export class ModelRebindingRun implements AgentRun {
     private readonly lifetime = new AbortController()
     private readonly controls = new Set<Promise<unknown>>()
 
-    constructor(run: AgentRun, private readonly reopen: (model: string, signal: AbortSignal) => Promise<AgentRun>, private readonly rootAdded?: (root: string) => void) {
+    constructor(run: AgentRun, private readonly reopen: (model: string, signal: AbortSignal, reasoningEffort?: AgentReasoningEffort) => Promise<AgentRun>, private readonly rootAdded?: (root: string) => void, private reasoningEffort?: AgentReasoningEffort) {
         this.run = run
         this.metadata = { ...run.metadata }
         this.events = new AgentEventStream(this.metadata)
@@ -42,7 +43,13 @@ export class ModelRebindingRun implements AgentRun {
         })
     }
 
-    respondUserInput: AgentRun['respondUserInput'] = async (command, options) => await this.withControl(signal => this.run.respondUserInput(command, { ...options, signal }), options)
+    respondUserInput: AgentRun['respondUserInput'] = async (command, options) => await this.withControl(async (signal) => {
+        const result = await this.run.respondUserInput(command, { ...options, signal })
+        if (result === 'submitted')
+            this.reasoningEffort = command.settings?.reasoningEffort ?? this.reasoningEffort
+        return result
+    }, options)
+
     interrupt: AgentRun['interrupt'] = async (command, options) => await this.withControl(signal => this.run.interrupt(command, { ...options, signal }), options)
     notify: NonNullable<AgentRun['notify']> = async (command, options) => await this.withControl(async (signal) => {
         if (!this.run.notify)
@@ -74,7 +81,56 @@ export class ModelRebindingRun implements AgentRun {
             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
+        const settings = command.settings ?? { model: command.model, reasoningEffort: command.reasoningEffort }
+        await this.rebind(settings.model ?? this.metadata.model, options)
+        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] : [])]) })
+        this.reasoningEffort = settings.reasoningEffort ?? this.reasoningEffort
+        if (acceptance.kind === 'turn' && acceptance.turnId !== this.lastEndedTurn)
+            this.activeTurn = acceptance.turnId
+        return acceptance
+    }
+
+    async changeSettings(command: ChangeSettingsAgentCommand, options: AgentOperationOptions = {}): Promise<void> {
+        if (this.stopped)
+            throw new AgentRunStateError({ message: 'The run stopped.' })
+        if (command.sessionId !== this.metadata.sessionId || command.providerSessionId !== this.metadata.providerSessionId || command.provider !== this.metadata.provider)
+            throw new AgentRunStateError({ message: 'Settings command does not target the bound run.' })
+        if (this.dispatching || this.workspaceChanging || this.controls.size || this.changing)
+            throw new AgentPromptDeferredError({ message: 'A provider operation is already in progress.' })
+        if (this.activeTurn)
+            throw new AgentPromptDeferredError({ message: 'Settings changes require an idle turn boundary.' })
+        this.settingsChanging = true
+        const task = this.dispatchSettings(command, options)
+        this.dispatching = task
+        try {
+            await task
+        }
+        finally {
+            this.dispatching = undefined
+            this.settingsChanging = false
+        }
+    }
+
+    private async dispatchSettings(command: ChangeSettingsAgentCommand, options: AgentOperationOptions): Promise<void> {
+        const signal = AbortSignal.any([this.lifetime.signal, ...(options.signal ? [options.signal] : [])])
+        signal.throwIfAborted()
+        // A failed legacy prompt rebind leaves the old run stopped. Recover its
+        // accepted settings before applying the new command on the replacement.
+        if (this.needsRebind)
+            await this.rebind(this.metadata.model ?? command.settings.model, { signal })
+        signal.throwIfAborted()
+        // Native settings updates configure the existing app-server thread, including
+        // empty threads. Keep the CLI and its warmed state instead of reopening it.
+        if (!this.run.changeSettings)
+            throw new AgentRunStateError({ message: 'The provider run does not support settings changes.' })
+        await this.run.changeSettings(command, { signal })
+        this.metadata.model = this.run.metadata.model
+        this.reasoningEffort = command.settings.reasoningEffort
+    }
+
+    private async rebind(model: string | undefined, options: AgentOperationOptions): Promise<void> {
         if (model && (this.needsRebind || model !== this.metadata.model)) {
             if (this.activeTurn)
                 throw new AgentPromptDeferredError({ message: 'Model changes require an idle turn boundary.' })
@@ -88,7 +144,7 @@ export class ModelRebindingRun implements AgentRun {
                 await this.run.stop({ type: 'agent.stop', ...this.target(), reason: 'model_rebind' }, { signal })
                 await this.pump
                 signal.throwIfAborted()
-                replacement = await this.reopen(model, signal)
+                replacement = await this.reopen(model, signal, this.reasoningEffort)
                 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
@@ -111,12 +167,6 @@ export class ModelRebindingRun implements AgentRun {
                 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) => {
@@ -138,7 +188,7 @@ export class ModelRebindingRun implements AgentRun {
     private async withControl<T>(operation: (signal: AbortSignal) => Promise<T>, options: AgentOperationOptions = {}): Promise<T> {
         if (this.stopped)
             throw new AgentRunStateError({ message: 'The run stopped.' })
-        if (this.changing || this.needsRebind)
+        if (this.settingsChanging || this.changing || this.needsRebind)
             throw new AgentPromptDeferredError({ message: 'The provider model is being rebound.' })
         const signal = AbortSignal.any([this.lifetime.signal, ...(options.signal ? [options.signal] : [])])
         const task = Promise.resolve().then(async () => {

package/src/protocol/agent-command.ts

@@ -90,10 +90,18 @@ export const respondUserInputAgentCommandSchema = runningCommandBaseSchema.exten
     commandId: commandIdSchema,
     requestId: z.string().min(1),
     answers: agentUserInputAnswersSchema,
+    settings: agentSettingsChangeSchema.optional(),
+})
+
+export const changeSettingsAgentCommandSchema = runningCommandBaseSchema.extend({
+    type: z.literal('agent.change-settings'),
+    commandId: commandIdSchema,
+    settings: z.strictObject({ model: agentModelIdSchema, reasoningEffort: agentReasoningEffortSchema }),
 })
 
 export const agentCommandSchema = z.union([
     sendPromptCommandSchema,
+    changeSettingsAgentCommandSchema,
     agentNotifyCommandSchema,
     interruptAgentCommandSchema,
     compactContextAgentCommandSchema,
@@ -112,3 +120,5 @@ export type CompactContextAgentCommand = z.infer<typeof compactContextAgentComma
 export type StopAgentCommand = z.infer<typeof stopAgentCommandSchema>
 export type RespondUserInputAgentCommand = z.infer<typeof respondUserInputAgentCommandSchema>
 export type AgentCommand = z.infer<typeof agentCommandSchema>
+
+export type ChangeSettingsAgentCommand = z.infer<typeof changeSettingsAgentCommandSchema>

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.2.0-experimental.6",
-    sha: "1b8f8c0c8cc698990c1b0ed9e03c417216bc0316",
-    buildTime: "2026-10-02T20:59:57.760Z",
+    version: "0.2.0-experimental.8",
+    sha: "4b63c95e2cc33fde3fbae56b5135006a2afac1e8",
+    buildTime: "2026-10-20T14:09:24.027Z",
 } as const

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

@@ -176,12 +176,18 @@ class AgentSupervisorRuntime implements SupervisorAgentRuntime {
 
     async ready(): Promise<void> { await this.recovered.promise }
 
-    async handle(input: Parameters<SupervisorAgentRuntime['handle']>[0]): Promise<void> {
+    async handle(input: Parameters<SupervisorAgentRuntime['handle']>[0]): ReturnType<SupervisorAgentRuntime['handle']> {
         this.attachEmitter(input.emit)
         await this.ready()
         if (this.eventFailure)
             throw this.eventFailure
         const metadata = this.input.run.metadata
+        if (input.body.type === 'agent.change-settings') {
+            if (!this.input.run.changeSettings)
+                throw new Error('Runtime does not support standalone settings changes.')
+            await this.input.run.changeSettings({ ...metadata, type: 'agent.change-settings', commandId: input.commandId, settings: input.body.settings }, { signal: input.signal })
+            return { appliedSettings: input.body.settings }
+        }
         if (input.body.type === 'agent.send-prompt') {
             const inputAttachmentPreparation = await this.input.prepareInputAttachments?.({
                 commandId: input.commandId,
@@ -196,6 +202,7 @@ class AgentSupervisorRuntime implements SupervisorAgentRuntime {
                 commandId: input.commandId,
                 mode: input.body.mode,
                 turnId: input.body.turnId,
+                settings: input.body.settings,
                 model: input.body.model,
                 reasoningEffort: input.body.reasoningEffort,
                 origin: 'user',
@@ -212,7 +219,13 @@ class AgentSupervisorRuntime implements SupervisorAgentRuntime {
                 inputAttachmentPreparation,
                 senderContext: input.body.user?.senderContext,
             })
-            return
+            // Both prompt formats can change later defaults. Omitted legacy fields must
+            // not overwrite accepted values, and settings takes whole-object precedence.
+            const settings = input.body.settings ?? {
+                ...(input.body.model === undefined ? {} : { model: input.body.model }),
+                ...(input.body.reasoningEffort === undefined ? {} : { reasoningEffort: input.body.reasoningEffort }),
+            }
+            return input.body.settings || Object.keys(settings).length ? { appliedSettings: settings } : undefined
         }
         if (input.body.type === 'agent.interrupt') {
             await this.input.run.interrupt({
@@ -225,7 +238,7 @@ class AgentSupervisorRuntime implements SupervisorAgentRuntime {
             }, { signal: input.signal })
             return
         }
-        await this.input.run.respondUserInput({
+        const submission = await this.input.run.respondUserInput({
             type: 'agent.respond-user-input',
             provider: metadata.provider,
             sessionId: metadata.sessionId,
@@ -233,7 +246,10 @@ class AgentSupervisorRuntime implements SupervisorAgentRuntime {
             commandId: input.commandId,
             requestId: input.body.requestId,
             answers: input.body.answers,
+            settings: input.body.settings,
         }, { signal: input.signal })
+        if (submission === 'submitted' && input.body.settings)
+            return { appliedSettings: input.body.settings }
     }
 
     async refreshSecrets(input: {

package/src/supervisor/persistence/supervisor-store.ts

@@ -1,3 +1,4 @@
+import type { AgentSettingsChange } from '../../protocol'
 import type { SessionBootstrapBody } from '../../supervisor-protocol/bootstrap'
 import type { CommandEnvelope } from '../../supervisor-protocol/envelopes/control-plane-to-supervisor'
 import type { DurableEventEnvelope } from '../../supervisor-protocol/envelopes/supervisor-to-control-plane'
@@ -6,6 +7,7 @@ import type { SupervisorAgentRunSnapshot } from '../../supervisor-protocol/super
 import { mkdirSync } from 'node:fs'
 import { dirname } from 'node:path'
 import { Database } from 'bun:sqlite'
+import { agentSettingsChangeSchema } from '../../protocol'
 import { sessionBootstrapBodySchema } from '../../supervisor-protocol/bootstrap'
 import { wireCommandBodySchema } from '../../supervisor-protocol/command-body'
 import { wireEventBodySchema } from '../../supervisor-protocol/event-body'
@@ -215,6 +217,27 @@ export class SupervisorStore {
         })()
     }
 
+    /** Restore accepted defaults in application order; the bootstrap remains immutable. */
+    appliedSettings(): AgentSettingsChange | undefined {
+        const row = this.database.query<{ value: string }, []>('SELECT value FROM metadata WHERE key = \'applied_settings\'').get()
+        return row ? agentSettingsChangeSchema.parse(JSON.parse(row.value)) : undefined
+    }
+
+    /** Commit settings, the outcome and inbox state together, including partial prompt/answer updates. */
+    finishCommand(input: { commandSeq: number, body: WireEventBody, appliedSettings?: AgentSettingsChange }): DurableEventEnvelope {
+        return this.database.transaction(() => {
+            const event = this.appendDurableEvent({ occurredAt: new Date().toISOString(), body: input.body })
+            const applied = input.body.type === 'supervisor.command.applied'
+            if (applied && input.appliedSettings) {
+                const settings = agentSettingsChangeSchema.parse({ ...this.appliedSettings(), ...input.appliedSettings })
+                this.database.query(`INSERT INTO metadata (key, value) VALUES ('applied_settings', ?)
+                    ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(canonicalJson(settings))
+            }
+            this.markCommand({ commandSeq: input.commandSeq, status: applied ? 'applied' : 'failed' })
+            return event
+        })()
+    }
+
     /** Commit before calling a provider: a process crash makes the outcome uncertain. */
     beginCommandDispatch(commandSeq: number): void {
         this.database.query('INSERT INTO command_dispatches(seq) VALUES (?)').run(commandSeq)
@@ -228,6 +251,12 @@ export class SupervisorStore {
                 JOIN command_dispatches ON command_dispatches.seq=commands.seq ORDER BY commands.seq
             `).all()
             for (const row of rows) {
+                // Reapplying a full settings pair is idempotent and submits no input. Prompt
+                // commands retain the existing uncertain-delivery policy below.
+                if (commandBodyFromRow(row).type === 'agent.change-settings') {
+                    this.database.query('DELETE FROM command_dispatches WHERE seq = ?').run(row.seq)
+                    continue
+                }
                 this.appendDurableEvent({
                     occurredAt: new Date().toISOString(),
                     body: {

package/src/supervisor/provider-factory.ts

@@ -1,3 +1,4 @@
+import type { AgentSettingsChange } from '../protocol'
 import type { EphemeralCredentials, SessionBootstrapBody, SessionBootstrapGitToken } from '../supervisor-protocol/bootstrap'
 import type { WireCommandBody } from '../supervisor-protocol/command-body'
 import type { WireEventBody } from '../supervisor-protocol/event-body'
@@ -13,7 +14,7 @@ export interface SupervisorAgentRuntime {
         body: WireCommandBody
         signal: AbortSignal
         emit: (body: WireEventBody) => void
-    }) => Promise<void>
+    }) => Promise<void | { appliedSettings: AgentSettingsChange }>
     refreshSecrets?: (input: {
         credentials?: EphemeralCredentials
         gitToken?: SessionBootstrapGitToken

package/src/supervisor/resident.ts

@@ -105,6 +105,7 @@ export async function createResidentSupervisor(input: {
             binding: binding.status,
             profile: input.profile,
             agentCore: agentCoreProvenance(),
+            capabilities: { 'model-change': 'v1' },
         }),
         getBoundSessionId: () => binding.status === 'bound' ? binding.sessionId : undefined,
         getLocalEventMax: () => binding.status === 'bound' ? binding.store.localEventMax() : 0,

package/src/supervisor/runtime-handler.ts

@@ -207,7 +207,7 @@ export class SupervisorRuntimeHandler implements RuntimeConnectionHandler {
                 gitToken: this.dependencies.gitToken,
             }
             this.createAgentTask = this.dependencies.providerFactory.create({
-                bootstrap: binding.body,
+                bootstrap: { ...binding.body, agent: { ...binding.body.agent, ...this.dependencies.store.appliedSettings() } },
                 ...initialSecrets,
                 rpc: this.rpc,
                 signal: this.lifecycleController.signal,
@@ -240,42 +240,42 @@ export class SupervisorRuntimeHandler implements RuntimeConnectionHandler {
         agent: SupervisorAgentRuntime
         command: CommandEnvelope & { body: WireCommandBody }
     }): Promise<void> {
+        this.dependencies.store.beginCommandDispatch(input.command.commandSeq)
+        let result: Awaited<ReturnType<SupervisorAgentRuntime['handle']>>
         try {
-            this.dependencies.store.beginCommandDispatch(input.command.commandSeq)
-            await input.agent.handle({
+            result = await input.agent.handle({
                 commandId: input.command.commandId,
                 commandSeq: input.command.commandSeq,
                 body: input.command.body,
                 signal: this.lifecycleController.signal,
                 emit: body => this.emit(body),
             })
-            this.dependencies.store.markCommand({ commandSeq: input.command.commandSeq, status: 'applied' })
-            this.emit({
-                type: 'supervisor.command.applied',
-                payload: {
-                    commandId: input.command.commandId,
-                    commandSeq: input.command.commandSeq,
-                    bodyType: input.command.body.type,
-                },
-            })
         }
-        catch {
+        catch (error) {
             if (this.lifecycleController.signal.aborted)
                 return
-            this.dependencies.store.markCommand({ commandSeq: input.command.commandSeq, status: 'failed' })
-            this.emit({
-                type: 'supervisor.command.failed',
-                payload: {
+            this.dependencies.logger.error({ err: error, commandId: input.command.commandId, bodyType: input.command.body.type }, 'Agent command execution failed')
+            this.sendEvent(this.dependencies.store.finishCommand({
+                commandSeq: input.command.commandSeq,
+                body: { type: 'supervisor.command.failed', payload: {
                     commandId: input.command.commandId,
                     commandSeq: input.command.commandSeq,
                     bodyType: input.command.body.type,
-                    failure: {
-                        type: 'command',
-                        detail: 'Agent command execution failed.',
-                    },
-                },
-            })
+                    failure: { type: 'command', detail: 'Agent command execution failed.' },
+                } },
+            }))
+            return
         }
+        // Persistence and socket errors must not turn an accepted command into a failed one.
+        this.sendEvent(this.dependencies.store.finishCommand({
+            commandSeq: input.command.commandSeq,
+            appliedSettings: result?.appliedSettings,
+            body: { type: 'supervisor.command.applied', payload: {
+                commandId: input.command.commandId,
+                commandSeq: input.command.commandSeq,
+                bodyType: input.command.body.type,
+            } },
+        }))
     }
 
     private emit(body: WireEventBody): void {

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

@@ -1,5 +1,5 @@
 import z from 'zod'
-import { agentPromptModeSchema, agentPromptSchema, agentReasoningEffortSchema, agentUserInputAnswersSchema, jsonObjectSchema, jsonUtf8ByteLength } from '../protocol'
+import { agentPromptModeSchema, agentPromptSchema, agentReasoningEffortSchema, agentSettingsChangeSchema, agentUserInputAnswersSchema, jsonObjectSchema, jsonUtf8ByteLength } from '../protocol'
 
 const wireSenderContextSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('application') }).strict(),
@@ -43,6 +43,7 @@ const wireSendPromptCommandSchema = z.object({
     turnId: z.string().min(1).optional(),
     model: z.string().trim().min(1).max(256).optional(),
     reasoningEffort: agentReasoningEffortSchema.optional(),
+    settings: agentSettingsChangeSchema.optional(),
     prompt: agentPromptSchema,
     attachments: z.array(wireInputAttachmentRefSchema).superRefine((attachments, context) => {
         const attachmentIds = new Set<string>()
@@ -69,10 +70,12 @@ const wireRespondUserInputCommandSchema = z.object({
     type: z.literal('agent.respond-user-input'),
     requestId: z.string().min(1),
     answers: agentUserInputAnswersSchema,
+    settings: agentSettingsChangeSchema.optional(),
     user: wireCommandUserSchema.optional(),
 }).strict()
 
 export const wireCommandBodySchema = z.discriminatedUnion('type', [
+    z.strictObject({ type: z.literal('agent.change-settings'), settings: z.strictObject({ model: z.string().trim().min(1).max(256), reasoningEffort: agentReasoningEffortSchema }) }),
     wireSendPromptCommandSchema,
     wireInterruptCommandSchema,
     wireRespondUserInputCommandSchema,