@meistrari/agent-core 0.2.0-experimental.7 → 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.7",
+    "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-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)

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

@@ -181,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> {

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'
@@ -274,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()
@@ -583,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'

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.7",
-    sha: "c27666274441cd3c81ffc5934ca115dffbe234ee",
-    buildTime: "2026-10-14T20:20:44.640Z",
+    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,