refactor(ai): trim effort update comments and tests

Co-authored-by: nexxeln <95541290+nexxeln@users.noreply.github.com>

packages/ai/AGENTS.md

@@ -165,6 +165,10 @@ Native chronological system messages are route/model-specific. Open Responses lo
 
 The wrapped-user fallback preserves ordering while visibly lowering authority. Never silently pass a raw chronological `role: "system"` through a route that might reject it. Do not insert raw retrieved documents, tool output, or web content into privileged chronological system updates; keep untrusted content in ordinary user/tool channels.
 
+### Effort Updates
+
+`Message.effort({ effort, previous })` is a chronological "reasoning effort changed here" marker (`undefined` means the model default). Changing a top-level effort invalidates the whole provider prompt cache, so protocols with a native per-message update (`Protocol.supportsEffortUpdates`) keep the top-level effort at the first marker's `previous` and lower each marker in place: Anthropic Messages emits an empty `role: "system"` message with `output_config.effort` plus the `mid-conversation-output-config-2026-07-01` beta, and OpenAI Responses emits `configuration_update` items. `applyEffortUpdates` runs in `prepareRequest` and strips the markers for every other route, so a protocol without support keeps today's plain top-level behaviour. When the last marker disagrees with the effort the request asks for (reverted or forked history), `resolveEffortUpdates` strips the markers and falls back to a plain top-level change.
+
 ### Tools
 
 Tool loops are represented in common messages and events:

packages/ai/src/cache-policy.ts

@@ -12,6 +12,7 @@
 // count against the four-breakpoint budget; auto only fills remaining slots.
 import { CacheHint, type CachePolicy, type CachePolicyObject } from "./schema/options.js"
 import { LLMRequest, Message, ToolDefinition, type ContentPart, type ToolEntry } from "./schema/messages.js"
+import { effortUpdate } from "./effort-updates.js"
 
 const AUTO: CachePolicyObject = {
   tools: true,
@@ -121,9 +122,15 @@ const markMessages = (
     return markMessageAt(messages, lastIndexOfRole(messages, "user"), hint, budget)
   if (strategy === "latest-assistant")
     return markMessageAt(messages, lastIndexOfRole(messages, "assistant"), hint, budget)
-  const start = Math.max(0, messages.length - strategy.tail)
+  let start = messages.length
+  let remaining = strategy.tail
+  while (remaining > 0 && start > 0) {
+    start -= 1
+    if (effortUpdate(messages[start]!) === undefined) remaining -= 1
+  }
   let next = messages
-  for (let i = start; i < messages.length; i++) next = markMessageAt(next, i, hint, budget)
+  for (let i = start; i < messages.length; i++)
+    if (effortUpdate(messages[i]!) === undefined) next = markMessageAt(next, i, hint, budget)
   return next
 }
 

packages/ai/src/effort-updates.ts

@@ -0,0 +1,27 @@
+// A top-level reasoning effort change invalidates the whole provider prompt cache, so a
+// mid-conversation switch travels as a `Message.effort(...)` marker: protocols with a native
+// per-message update freeze the top-level effort and lower the markers; every other route strips them.
+import { LLMRequest, type EffortPart, type Message } from "./schema/messages.js"
+
+export const effortUpdate = (message: Message): EffortPart | undefined => {
+  if (message.role !== "system" || message.content.length !== 1) return undefined
+  const part = message.content[0]
+  return part.type === "effort" ? part : undefined
+}
+
+export const stripEffortUpdates = (request: LLMRequest) => {
+  const messages = request.messages.filter((message) => effortUpdate(message) === undefined)
+  return messages.length === request.messages.length ? request : LLMRequest.update(request, { messages })
+}
+
+export const applyEffortUpdates = (request: LLMRequest): LLMRequest =>
+  request.model.route.supportsEffortUpdates?.(request) ? request : stripEffortUpdates(request)
+
+// The markers must end at `current`: `revert.ts` never touches `session.model` and forks may select
+// another variant, so on disagreement fall back to a plain top-level change instead of misreporting effort.
+export const resolveEffortUpdates = (request: LLMRequest, current: string | undefined) => {
+  const updates = request.messages.flatMap((message) => effortUpdate(message) ?? [])
+  if (updates.length === 0) return { request, effort: current }
+  if (updates.at(-1)?.effort !== current) return { request: stripEffortUpdates(request), effort: current }
+  return { request, effort: updates[0]?.previous }
+}

packages/ai/src/protocols/anthropic-messages.ts

@@ -27,6 +27,7 @@ import {
 } from "../schema/index.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { classifyProviderFailure } from "../provider-error.js"
+import { effortUpdate, resolveEffortUpdates } from "../effort-updates.js"
 import * as Cache from "./utils/cache.js"
 import { Lifecycle } from "./utils/lifecycle.js"
 import { ToolSchemaProjection } from "./utils/tool-schema.js"
@@ -36,6 +37,7 @@ const ADAPTER = "anthropic-messages"
 export const DEFAULT_BASE_URL = "https://api.anthropic.com/v1"
 export const PATH = "/messages"
 export const DEFAULT_MAX_TOKENS = 32_000
+const DEFAULT_EFFORT = "high"
 
 const SSE_EVENTS = new Set([
   "message",
@@ -286,7 +288,11 @@ type AnthropicToolResultBlock = Schema.Schema.Type<typeof AnthropicToolResultBlo
 const AnthropicMessage = Schema.Union([
   Schema.Struct({ role: Schema.Literal("user"), content: Schema.Array(AnthropicUserBlock) }),
   Schema.Struct({ role: Schema.Literal("assistant"), content: Schema.Array(AnthropicAssistantBlock) }),
-  Schema.Struct({ role: Schema.Literal("system"), content: Schema.Array(AnthropicTextBlock) }),
+  Schema.Struct({
+    role: Schema.Literal("system"),
+    content: Schema.Array(AnthropicTextBlock),
+    output_config: Schema.optional(Schema.Struct({ effort: Schema.String })),
+  }),
 ]).pipe(Schema.toTaggedUnion("role"))
 type AnthropicMessage = Schema.Schema.Type<typeof AnthropicMessage>
 
@@ -877,6 +883,12 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
 
   for (const [index, message] of request.messages.entries()) {
     if (message.role === "system") {
+      const update = effortUpdate(message)
+      if (update) {
+        // Accepted at any position, so the text-update placement rules do not apply.
+        messages.push({ role: "system", content: [], output_config: { effort: update.effort ?? DEFAULT_EFFORT } })
+        continue
+      }
       if (splitsLocalToolResults(request.messages, index))
         return yield* invalid("Anthropic Messages system updates cannot split a local tool call from its tool result")
       if (supportsNativeSystemUpdates(request) && canUseNativeSystemUpdate(request, index)) {
@@ -1034,18 +1046,11 @@ const resolveOptions = Effect.fn("AnthropicMessages.resolveOptions")(function* (
     ProviderShared.isRecord(rawOutputConfig) && ProviderShared.isRecord(rawOutputConfig.format)
       ? (rawOutputConfig.format as { type: "json_schema"; schema: Record<string, unknown> })
       : undefined
-  const output_config =
-    outputConfigEffort === undefined && outputConfigFormat === undefined
-      ? undefined
-      : {
-          ...(outputConfigEffort === undefined ? {} : { effort: outputConfigEffort }),
-          ...(outputConfigFormat === undefined ? {} : { format: outputConfigFormat }),
-        }
   const thinking = yield* resolveThinking(input?.thinking)
   return {
     thinking: applyThinkingBindingDefault(request.model, thinking),
     effort: outputConfigEffort,
-    output_config,
+    format: outputConfigFormat,
     service_tier,
     metadata,
     container,
@@ -1054,15 +1059,30 @@ const resolveOptions = Effect.fn("AnthropicMessages.resolveOptions")(function* (
   }
 })
 
+// Accept gateway namespaces and Vertex suffixes without treating a snapshot date as a minor version.
+const claudeVersion = (id: string) => {
+  const match = /(?:^|[./])claude-(?<family>[a-z]+)-(?<major>\d+)(?:[.-](?<minor>\d{1,2}))?(?:$|[-:@])/.exec(
+    id.toLowerCase(),
+  )?.groups
+  if (!match) return undefined
+  return { family: match.family, major: Number(match.major), minor: Number(match.minor ?? 0) }
+}
+
 const supportsThinkingBlockBinding = (model: LLMRequest["model"]) => {
   const override = model.compatibility?.supportsThinkingBlockBinding
   if (override !== undefined) return override
-  // Accept gateway namespaces and Vertex suffixes without treating a snapshot date as a minor version.
-  const version = /(?:^|[./])claude-[a-z]+-(?<major>\d+)(?:[.-](?<minor>\d{1,2}))?(?:$|[-:@])/i.exec(model.id)?.groups
-  if (!version) return false
-  const major = Number(version.major)
-  const minor = Number(version.minor ?? 0)
-  return major > 5 || (major === 5 && minor >= 1)
+  const version = claudeVersion(model.id)
+  return version !== undefined && (version.major > 5 || (version.major === 5 && version.minor >= 1))
+}
+
+const supportsEffortUpdates = (model: LLMRequest["model"]) => {
+  const override = model.compatibility?.supportsEffortUpdates
+  if (override !== undefined) return override
+  const version = claudeVersion(model.id)
+  if (version === undefined) return false
+  if (version.family === "opus") return version.major >= 5
+  if (version.family !== "fable" && version.family !== "mythos") return false
+  return version.major > 5 || (version.major === 5 && version.minor >= 1)
 }
 
 const applyThinkingBindingDefault = (model: LLMRequest["model"], thinking: AnthropicThinking | undefined) => {
@@ -1104,13 +1124,15 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
   const management = yield* ProviderShared.validateWith(
     Schema.decodeUnknownEffect(Schema.UndefinedOr(ContextManagement)),
   )(request.providerOptions?.contextManagement)
+  const options = yield* resolveOptions(request)
+  const updates = resolveEffortUpdates(request, options.effort)
   const generation = request.generation
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
   // Allocate the 4-breakpoint budget in invalidation order: tools → system →
   // messages. Tools live highest in the cache hierarchy, so when callers
   // over-mark we keep their tool hints and shed the message-tail ones first.
   const breakpoints = Cache.newBreakpoints(ANTHROPIC_BREAKPOINT_CAP)
-  const flattened = ProviderShared.flattenToolRequest(request)
+  const flattened = ProviderShared.flattenToolRequest(updates.request)
   const tools =
     flattened.tools.length === 0
       ? undefined
@@ -1138,7 +1160,13 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
       `Anthropic Messages: dropped ${breakpoints.dropped} cache breakpoint(s); the API allows at most ${ANTHROPIC_BREAKPOINT_CAP} per request.`,
     )
   }
-  const options = yield* resolveOptions(request)
+  const output_config =
+    updates.effort === undefined && options.format === undefined
+      ? undefined
+      : {
+          ...(updates.effort === undefined ? {} : { effort: updates.effort }),
+          ...(options.format === undefined ? {} : { format: options.format }),
+        }
   const body = {
     model: request.model.id,
     system,
@@ -1152,7 +1180,7 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
     top_k: generation?.topK,
     stop_sequences: generation?.stop,
     thinking: options.thinking,
-    output_config: options.output_config,
+    output_config,
     // top-level passthrough per SDK MessageCreateParamsBase:4638,4643,4649,4654,4670
     cache_control: options.cache_control,
     container: options.container,
@@ -1677,6 +1705,7 @@ export const protocol = Protocol.make({
     }),
     step,
   },
+  supportsEffortUpdates: (request) => supportsEffortUpdates(request.model),
 })
 
 export const transport = <
@@ -1715,6 +1744,9 @@ function requiredBetaHeaders(body: Pick<AnthropicMessagesBody, "messages" | "con
   )
   if (requestsCompaction || replaysCompaction) betas.push("compact-2026-01-12")
 
+  if (body.messages.some((message) => message.role === "system" && message.output_config !== undefined))
+    betas.push("mid-conversation-output-config-2026-07-01")
+
   const thinking = body.thinking
   if (thinking && thinking.type !== "disabled" && thinking.block_binding)
     betas.push("thinking-binding-controls-2026-08-01")

packages/ai/src/protocols/open-responses.ts

@@ -20,6 +20,7 @@ import {
 } from "../schema/index.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { classifyProviderFailure } from "../provider-error.js"
+import { effortUpdate } from "../effort-updates.js"
 import { OpenResponsesOptions } from "./utils/open-responses-options.js"
 import { Lifecycle } from "./utils/lifecycle.js"
 import { ToolSchemaProjection } from "./utils/tool-schema.js"
@@ -164,6 +165,13 @@ export const CompactionItem = Schema.Struct({
   encrypted_content: Schema.String,
 })
 
+// Kept out of the baseline `InputItem` union: only the OpenAI extension accepts it.
+export const ConfigurationUpdate = Schema.Struct({
+  type: Schema.Literal("configuration_update"),
+  reasoning: Schema.Struct({ effort: OpenResponsesOptions.ReasoningEffort }),
+})
+type ConfigurationUpdate = Schema.Schema.Type<typeof ConfigurationUpdate>
+
 export const InputItem = Schema.Union([
   CompactionItem,
   Schema.Struct({ role: Schema.tag("system"), content: Schema.String }),
@@ -208,6 +216,7 @@ export type HostedToolReplayItem = {
 type LoweredInputItem =
   | OpenResponsesInputItem
   | HostedToolReplayItem
+  | ConfigurationUpdate
   | {
       readonly type: "message"
       readonly id?: string
@@ -634,6 +643,8 @@ const lowerToolResultOutput = Effect.fnUntraced(function* (
   return yield* Effect.forEach(content, (item) => lowerToolResultContentItem(item, request, adapter))
 })
 
+const DEFAULT_EFFORT = "medium"
+
 const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
   request: LLMRequest,
   adapter: ProviderAdapter,
@@ -646,6 +657,14 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
       Schema.decodeUnknownEffect(Schema.UndefinedOr(MessageMetadata)),
     )(message.providerMetadata?.[providerMetadataKey])
     if (message.role === "system") {
+      const update = effortUpdate(message)
+      if (update) {
+        // Consecutive updates are rejected, so a newer one replaces its predecessor.
+        const last = input.at(-1)
+        if (last !== undefined && "type" in last && last.type === "configuration_update") input.pop()
+        input.push({ type: "configuration_update", reasoning: { effort: update.effort ?? DEFAULT_EFFORT } })
+        continue
+      }
       input.push({
         role: "developer",
         content: ProviderShared.joinText(yield* ProviderShared.systemUpdateText(adapter.name, message)),
@@ -789,8 +808,7 @@ export const lowerConversation = Effect.fn("OpenResponses.lowerConversation")(fu
   }
 })
 
-export const lowerGeneration = (request: LLMRequest) => {
-  const options = OpenResponsesOptions.resolve(request)
+export const lowerGeneration = (request: LLMRequest, options = OpenResponsesOptions.resolve(request)) => {
   const generation = request.generation
   const cacheKey = ProviderShared.promptCacheKey(request)
   const parallelToolCalls = resolveParallelToolCalls(request)

packages/ai/src/protocols/openai-responses.ts

@@ -6,7 +6,9 @@ import { Endpoint } from "../route/endpoint.js"
 import { Protocol } from "../route/protocol.js"
 import { HttpTransport } from "../route/transport/index.js"
 import { LLMRequest, mergeJsonRecords, type JsonSchema, type ToolDefinition, type ToolEntry } from "../schema/index.js"
+import { resolveEffortUpdates } from "../effort-updates.js"
 import { OpenResponses } from "./open-responses.js"
+import { OpenResponsesOptions } from "./utils/open-responses-options.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { OpenAIImage } from "./utils/openai-image.js"
 import { ResponsesHostedTools } from "./utils/responses-hosted-tools.js"
@@ -94,9 +96,15 @@ const OpenAIResponsesToolChoice = Schema.Union([
   Schema.Struct({ type: Schema.tag("image_generation") }),
 ])
 
+const OpenAIResponsesInputItem = Schema.Union([
+  OpenResponses.InputItem,
+  OpenAIResponsesHostedToolItem,
+  OpenResponses.ConfigurationUpdate,
+])
+
 const OpenAIResponsesCoreFields = {
   ...OpenResponses.coreFields,
-  input: Schema.Array(Schema.Union([OpenResponses.InputItem, OpenAIResponsesHostedToolItem])),
+  input: Schema.Array(OpenAIResponsesInputItem),
   tools: optionalArray(OpenAIResponsesTools),
   tool_choice: Schema.optional(OpenAIResponsesToolChoice),
   context_management: Schema.optional(
@@ -119,7 +127,7 @@ export type OpenAIResponsesBody = Schema.Schema.Type<typeof OpenAIResponsesBody>
 export const CompactionTrigger = Schema.Struct({ type: Schema.Literal("compaction_trigger") })
 const CheckpointBody = Schema.Struct({
   ...OpenAIResponsesBody.fields,
-  input: Schema.Array(Schema.Union([OpenResponses.InputItem, OpenAIResponsesHostedToolItem, CompactionTrigger])),
+  input: Schema.Array(Schema.Union([OpenAIResponsesInputItem, CompactionTrigger])),
   store: Schema.Literal(false),
   prompt_cache_retention: optionalNull(Schema.String),
   prompt_cache_options: optionalNull(
@@ -133,6 +141,14 @@ const adapter = {
   restoreHostedToolItem: (item: unknown) => (Schema.is(OpenAIResponsesHostedToolItem)(item) ? item : undefined),
 } satisfies OpenResponses.ProviderAdapter
 
+// Only GPT-6 Astra accepts `configuration_update`, and never alongside automatic `context_management` compaction.
+const supportsEffortUpdates = (request: LLMRequest) => {
+  if (request.providerOptions?.contextManagement !== undefined) return false
+  const override = request.model.compatibility?.supportsEffortUpdates
+  if (override !== undefined) return override
+  return /(?:^|\/)gpt-6-astra$/i.test(request.model.id)
+}
+
 const nativeImageToolInput = (tool: ToolDefinition) => {
   const native = tool.native?.openai
   return ProviderShared.isRecord(native) && native.type === "image_generation" ? native : undefined
@@ -189,10 +205,12 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
   const management = yield* ProviderShared.validateWith(
     Schema.decodeUnknownEffect(Schema.UndefinedOr(ContextManagement)),
   )(request.providerOptions?.contextManagement)
+  const options = OpenResponsesOptions.resolve(request)
+  const updates = resolveEffortUpdates(request, options.reasoningEffort)
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
   return yield* decodeBody({
-    ...(yield* OpenResponses.lowerConversation(request, adapter)),
-    ...OpenResponses.lowerGeneration(request),
+    ...(yield* OpenResponses.lowerConversation(updates.request, adapter)),
+    ...OpenResponses.lowerGeneration(request, { ...options, reasoningEffort: updates.effort }),
     context_management: management?.map((edit) => ({ type: edit.type, compact_threshold: edit.compactThreshold })),
     tools:
       request.tools.length === 0
@@ -295,6 +313,7 @@ export const protocol = Protocol.make({
     step,
     terminal: OpenResponses.terminal,
   },
+  supportsEffortUpdates,
 })
 
 const endpoint = Endpoint.path<OpenAIResponsesBody>(PATH, { baseURL: DEFAULT_BASE_URL })

packages/ai/src/protocols/utils/open-responses-options.ts

@@ -1,12 +1,7 @@
 import { Option, Schema } from "effect"
-import type { LLMRequest } from "../../schema/index.js"
+import { ReasoningEffort, ReasoningEfforts, type LLMRequest } from "../../schema/index.js"
 
-export const ReasoningEfforts = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const
-export type ReasoningEffort = (typeof ReasoningEfforts)[number] | (string & {})
-export const ReasoningEffort = Schema.declare<ReasoningEffort>(
-  (value): value is ReasoningEffort => typeof value === "string",
-  { title: "ReasoningEffort" },
-)
+export { ReasoningEffort, ReasoningEfforts }
 
 export const TextVerbosities = ["low", "medium", "high"] as const
 export type TextVerbosity = (typeof TextVerbosities)[number] | (string & {})

packages/ai/src/protocols/utils/responses-compaction.ts

@@ -11,6 +11,7 @@ import {
   mergeJsonRecords,
 } from "../../schema/index.js"
 import type { CompactOperation } from "../../route/client.js"
+import { stripEffortUpdates } from "../../effort-updates.js"
 import { Endpoint } from "../../route/endpoint.js"
 import { RequestExecutor } from "../../route/executor.js"
 import { HttpTransport } from "../../route/transport/index.js"
@@ -75,7 +76,8 @@ const Response = Schema.Struct({
 export const make = (adapter: OpenResponses.ProviderAdapter): CompactOperation =>
   Effect.fn("ResponsesCompaction.execute")(function* (request, executor, options) {
     const route = request.model.route
-    const native = yield* OpenResponses.lowerConversation(request, adapter)
+    // The standalone compaction endpoint rejects histories containing configuration updates.
+    const native = yield* OpenResponses.lowerConversation(stripEffortUpdates(request), adapter)
     const body = yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(Body))(
       mergeJsonRecords(
         {

packages/ai/src/route/client.ts

@@ -7,6 +7,7 @@ import { HttpTransport } from "./transport/index.js"
 import type { HttpMiddleware, Transport, TransportRuntime, WebSocketChannelExecutor } from "./transport/index.js"
 import type { Protocol } from "./protocol.js"
 import { applyCachePolicy } from "../cache-policy.js"
+import { applyEffortUpdates } from "../effort-updates.js"
 import { normalizeToolHistory } from "../tool-history.js"
 import { sanitizeSurrogates } from "../utils/sanitize.js"
 import * as ProviderShared from "../protocols/shared.js"
@@ -55,6 +56,7 @@ export interface Route<
   readonly transport: Transport<Body, Prepared, unknown>
   readonly defaults: RouteDefaults
   readonly body: RouteBody<Body>
+  readonly supportsEffortUpdates?: (request: LLMRequest) => boolean
   readonly with: {
     <Next extends CompactionOperations | undefined>(
       patch: RoutePatch<Body, Prepared> & { readonly compact: Next },
@@ -388,6 +390,7 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
       transport: routeInput.transport,
       defaults: routeInput.defaults ?? {},
       body: protocol.body,
+      supportsEffortUpdates: protocol.supportsEffortUpdates,
       with: (patch: RoutePatch<Body, Prepared>) => {
         const { compact, id, provider, providerMetadataKey, auth, transport, endpoint, ...defaults } = patch
         return build({
@@ -558,7 +561,9 @@ const prepareRequest = (request: LLMRequest) => {
     [...new Map(tools.map((tool) => [`${tool.type}:${tool.name}`, tool])).values()].map((tool) =>
       tool.type === "tool" ? tool : { ...tool, tools: dedupe(tool.tools) },
     )
-  const resolved = applyCachePolicy(LLMRequest.update(sanitized, { tools: dedupe(sanitized.tools) }))
+  const resolved = applyCachePolicy(
+    applyEffortUpdates(LLMRequest.update(sanitized, { tools: dedupe(sanitized.tools) })),
+  )
   const headers = resolved.model.route.headers?.({ request: resolved })
   return headers === undefined
     ? resolved

packages/ai/src/route/protocol.ts

@@ -41,6 +41,8 @@ export interface Protocol<Body, Frame, Event, State> {
   readonly body: ProtocolBody<Body>
   /** Response side: streaming state machine. */
   readonly stream: ProtocolStream<Frame, Event, State>
+  /** Whether `body.from` lowers `Message.effort(...)` markers; wrappers around another `body.from` must forward it. */
+  readonly supportsEffortUpdates?: (request: LLMRequest) => boolean
 }
 
 export interface ProtocolBody<Body> {

packages/ai/src/schema/messages.ts

@@ -9,6 +9,7 @@ import {
   LanguageModelSchema,
   type LanguageModel,
   ProviderOptions,
+  ReasoningEffort,
 } from "./options.js"
 import { ProviderID } from "./ids.js"
 
@@ -217,6 +218,14 @@ export const CompactionPart = Object.assign(compactionPartSchema, {
     Schema.decodeUnknownSync(compactionPartSchema)({ type: "compaction", ...input }),
 })
 
+/** Reasoning effort changed here, from `previous` to `effort`; `undefined` is the model default. */
+export const EffortPart = Schema.Struct({
+  type: Schema.Literal("effort"),
+  effort: Schema.optional(ReasoningEffort),
+  previous: Schema.optional(ReasoningEffort),
+}).annotate({ identifier: "LLM.Content.Effort" })
+export type EffortPart = Schema.Schema.Type<typeof EffortPart>
+
 export const ContentPart = Schema.Union([
   TextPart,
   MediaPart,
@@ -224,6 +233,7 @@ export const ContentPart = Schema.Union([
   ToolResultPart,
   ReasoningPart,
   CompactionPart,
+  EffortPart,
 ]).pipe(Schema.toTaggedUnion("type"))
 export type ContentPart = Schema.Schema.Type<typeof ContentPart>
 
@@ -265,6 +275,9 @@ export namespace Message {
    */
   export const system = (content: SystemContentInput) => make({ role: "system", content })
 
+  export const effort = (input: { readonly effort?: ReasoningEffort; readonly previous?: ReasoningEffort }) =>
+    make({ role: "system", content: [{ type: "effort", effort: input.effort, previous: input.previous }] })
+
   export const tool = (result: ToolResultPart | Parameters<typeof ToolResultPart.make>[0]) =>
     make({ role: "tool", content: ["type" in result ? result : ToolResultPart.make(result)] })
 }

packages/ai/src/schema/options.ts

@@ -140,6 +140,14 @@ export namespace LanguageModelDefaults {
   }
 }
 
+/** Ordered lowest to highest. */
+export const ReasoningEfforts = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const
+export type ReasoningEffort = (typeof ReasoningEfforts)[number] | (string & {})
+export const ReasoningEffort = Schema.declare<ReasoningEffort>(
+  (value): value is ReasoningEffort => typeof value === "string",
+  { title: "ReasoningEffort" },
+)
+
 export const LanguageModelToolSchemaCompatibility = Schema.Literals(["gemini", "moonshot"])
 export type LanguageModelToolSchemaCompatibility = Schema.Schema.Type<typeof LanguageModelToolSchemaCompatibility>
 
@@ -165,6 +173,8 @@ export class LanguageModelCompatibility extends Schema.Class<LanguageModelCompat
   requireSignature: Schema.optional(Schema.Boolean),
   /** Supports Anthropic's thinking-prefix mismatch controls. Overrides model-ID detection. */
   supportsThinkingBlockBinding: Schema.optional(Schema.Boolean),
+  /** Supports per-message effort updates. Overrides model-ID detection. */
+  supportsEffortUpdates: Schema.optional(Schema.Boolean),
 }) {}
 
 export namespace LanguageModelCompatibility {

packages/ai/test/effort-updates.test.ts

@@ -0,0 +1,439 @@
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { LLM, LLMRequest, Message, ToolCallPart } from "../src/index.js"
+import { Auth, LLMClient } from "../src/route.js"
+import { compileRequest } from "../src/route/client.js"
+import { AnthropicMessages } from "../src/protocols/anthropic-messages.js"
+import { OpenAIResponses } from "../src/protocols/openai-responses.js"
+import { Gemini } from "../src/protocols/gemini.js"
+import { GoogleVertexMessages, OpenAI } from "../src/providers.js"
+import { applyCachePolicy } from "../src/cache-policy.js"
+import { applyEffortUpdates } from "../src/effort-updates.js"
+import { it, testEffect } from "./lib/effect.js"
+import { dynamicResponse } from "./lib/http.js"
+import { sseEvents } from "./lib/sse.js"
+
+const anthropic = (id: string, compatibility?: { readonly supportsEffortUpdates?: boolean }) =>
+  AnthropicMessages.route
+    .with({ endpoint: { baseURL: "https://api.anthropic.test/v1/" }, auth: Auth.header("x-api-key", "test") })
+    .model({ id, compatibility })
+
+const openai = (id: string, compatibility?: { readonly supportsEffortUpdates?: boolean }) =>
+  OpenAIResponses.route
+    .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
+    .model({ id, compatibility })
+
+const opus5 = anthropic("claude-opus-5")
+const astra = openai("gpt-6-astra")
+
+const lowFromHigh = Message.effort({ effort: "low", previous: "high" })
+const conversation = [Message.user("Before."), lowFromHigh, Message.user("After.")]
+
+const systemMessages = (body: AnthropicMessages.AnthropicMessagesBody) =>
+  body.messages.filter((message) => message.role === "system")
+
+const updates = (body: OpenAIResponses.OpenAIResponsesBody) =>
+  body.input.filter((item) => "type" in item && item.type === "configuration_update")
+
+describe("applyEffortUpdates", () => {
+  test("keeps the request identity without markers and for protocols that lower them", () => {
+    const plain = LLM.request({ model: opus5, prompt: "hi" })
+    expect(applyEffortUpdates(plain)).toBe(plain)
+
+    const supported = LLM.request({ model: opus5, messages: conversation, providerOptions: { effort: "low" } })
+    expect(applyEffortUpdates(supported)).toBe(supported)
+  })
+
+  it.effect("compiles markers away for protocols without per-message effort", () =>
+    Effect.gen(function* () {
+      const model = Gemini.route
+        .with({
+          endpoint: { baseURL: "https://generativelanguage.test/v1beta/" },
+          auth: Auth.header("x-goog-api-key", "test"),
+        })
+        .model({ id: "gemini-3.5-flash" })
+      const withMarkers = yield* compileRequest(LLM.request({ model, messages: conversation }))
+      const withoutMarkers = yield* compileRequest(
+        LLM.request({ model, messages: [Message.user("Before."), Message.user("After.")] }),
+      )
+
+      expect(withMarkers.body).toEqual(withoutMarkers.body)
+    }),
+  )
+})
+
+describe("cache policy", () => {
+  it.effect("walks the tail breakpoint back past a trailing effort marker", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: opus5,
+          messages: [Message.user("first"), Message.assistant("reply"), Message.user("latest"), lowFromHigh],
+          providerOptions: { effort: "low" },
+          cache: "auto",
+        }),
+      )
+
+      expect(prepared.body.messages).toEqual([
+        { role: "user", content: [{ type: "text", text: "first" }] },
+        { role: "assistant", content: [{ type: "text", text: "reply" }] },
+        { role: "user", content: [{ type: "text", text: "latest", cache_control: { type: "ephemeral" } }] },
+        { role: "system", content: [], output_config: { effort: "low" } },
+      ])
+    }),
+  )
+})
+
+describe("Anthropic Messages effort updates", () => {
+  it.effect("lowers markers to per-turn system messages and freezes the top-level effort", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({ model: opus5, messages: conversation, providerOptions: { effort: "low" }, cache: "none" }),
+      )
+
+      expect(prepared.body.output_config).toEqual({ effort: "high" })
+      expect(prepared.body.messages).toEqual([
+        { role: "user", content: [{ type: "text", text: "Before." }] },
+        { role: "system", content: [], output_config: { effort: "low" } },
+        { role: "user", content: [{ type: "text", text: "After." }] },
+      ])
+    }),
+  )
+
+  it.effect("omits the frozen effort for the model default and sends `high` for a switch back to it", () =>
+    Effect.gen(function* () {
+      const format = { type: "json_schema" as const, schema: { type: "object" } }
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: opus5,
+          messages: [
+            Message.user("One."),
+            Message.effort({ effort: "low" }),
+            Message.user("Two."),
+            Message.effort({ previous: "low" }),
+            Message.user("Three."),
+          ],
+          providerOptions: { output_config: { format } },
+          cache: "none",
+        }),
+      )
+
+      expect(prepared.body.output_config).toEqual({ format })
+      expect(systemMessages(prepared.body)).toEqual([
+        { role: "system", content: [], output_config: { effort: "low" } },
+        { role: "system", content: [], output_config: { effort: "high" } },
+      ])
+    }),
+  )
+
+  it.effect("requests the mid-conversation output config beta only when markers are sent", () =>
+    Effect.gen(function* () {
+      for (const [model, betas] of [
+        [opus5, "existing-beta,mid-conversation-output-config-2026-07-01"],
+        [anthropic("claude-sonnet-5"), "existing-beta"],
+      ] as const) {
+        const request = LLM.request({
+          model,
+          messages: conversation,
+          providerOptions: { effort: "low" },
+          http: { headers: { "anthropic-beta": "existing-beta" } },
+        })
+        const compiled = yield* compileRequest(request)
+        const prepared = yield* AnthropicMessages.route.prepareTransport(compiled.body, request)
+        expect(prepared.request.headers["anthropic-beta"]).toBe(betas)
+      }
+    }),
+  )
+
+  it.effect("accepts a marker between a tool call and its result", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: opus5,
+          messages: [
+            Message.user("Weather?"),
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: {} })]),
+            lowFromHigh,
+            Message.tool({ id: "call_1", name: "lookup", result: { temp: 72 } }),
+          ],
+          providerOptions: { effort: "low" },
+          cache: "none",
+        }),
+      )
+
+      expect(prepared.body.messages).toEqual([
+        { role: "user", content: [{ type: "text", text: "Weather?" }] },
+        { role: "assistant", content: [{ type: "tool_use", id: "call_1", name: "lookup", input: {} }] },
+        { role: "system", content: [], output_config: { effort: "low" } },
+        { role: "user", content: [{ type: "tool_result", tool_use_id: "call_1", content: '{"temp":72}' }] },
+      ])
+    }),
+  )
+
+  it.effect("falls back to a plain top-level effort when history drifted from the current effort", () =>
+    Effect.gen(function* () {
+      const drifted = yield* compileRequest(
+        LLM.request({ model: opus5, messages: conversation, providerOptions: { effort: "medium" }, cache: "none" }),
+      )
+      const plain = yield* compileRequest(
+        LLM.request({
+          model: opus5,
+          messages: [Message.user("Before."), Message.user("After.")],
+          providerOptions: { effort: "medium" },
+          cache: "none",
+        }),
+      )
+
+      expect(drifted.body).toEqual(plain.body)
+      expect(drifted.body.output_config).toEqual({ effort: "medium" })
+    }),
+  )
+
+  for (const [id, supported] of [
+    ["claude-opus-5", true],
+    ["claude-opus-5-20260901", true],
+    ["anthropic/claude-opus-5", true],
+    ["claude-fable-5-1", true],
+    ["claude-mythos-5-1", true],
+    ["claude-fable-5", false],
+    ["claude-opus-4-8", false],
+    ["claude-sonnet-5", false],
+    ["kimi-k2.5", false],
+  ] as const) {
+    it.effect(`${supported ? "lowers" : "strips"} markers for ${id}`, () =>
+      Effect.gen(function* () {
+        const prepared = yield* compileRequest(
+          LLM.request({ model: anthropic(id), messages: conversation, providerOptions: { effort: "low" } }),
+        )
+
+        expect(systemMessages(prepared.body)).toHaveLength(supported ? 1 : 0)
+        expect(prepared.body.output_config).toEqual({ effort: supported ? "high" : "low" })
+      }),
+    )
+  }
+
+  it.effect("honors the compatibility override in both directions", () =>
+    Effect.gen(function* () {
+      const enabled = yield* compileRequest(
+        LLM.request({
+          model: anthropic("claude-sonnet-5", { supportsEffortUpdates: true }),
+          messages: conversation,
+          providerOptions: { effort: "low" },
+        }),
+      )
+      const disabled = yield* compileRequest(
+        LLM.request({
+          model: anthropic("claude-opus-5", { supportsEffortUpdates: false }),
+          messages: conversation,
+          providerOptions: { effort: "low" },
+        }),
+      )
+
+      expect(systemMessages(enabled.body)).toHaveLength(1)
+      expect(systemMessages(disabled.body)).toHaveLength(0)
+    }),
+  )
+
+  it.effect("strips markers on the Vertex Anthropic route, whose protocol wrapper does not forward support", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: GoogleVertexMessages.configure({ accessToken: "test", location: "global", project: "test" }).model(
+            "claude-opus-5",
+          ),
+          messages: conversation,
+          providerOptions: { effort: "low" },
+        }),
+      )
+
+      expect(systemMessages(prepared.body)).toHaveLength(0)
+      expect(prepared.body.output_config).toEqual({ effort: "low" })
+    }),
+  )
+})
+
+describe("OpenAI Responses effort updates", () => {
+  it.effect("lowers markers to configuration_update items and freezes reasoning.effort", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({ model: astra, messages: conversation, providerOptions: { reasoningEffort: "low" } }),
+      )
+
+      expect(prepared.body.reasoning).toEqual({ effort: "high" })
+      expect(prepared.body.input).toEqual([
+        { role: "user", content: [{ type: "input_text", text: "Before." }] },
+        { type: "configuration_update", reasoning: { effort: "low" } },
+        { role: "user", content: [{ type: "input_text", text: "After." }] },
+      ])
+    }),
+  )
+
+  it.effect("coalesces consecutive updates so the newest wins", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: astra,
+          messages: [
+            Message.user("Before."),
+            Message.effort({ effort: "low", previous: "medium" }),
+            Message.effort({ effort: "xhigh", previous: "low" }),
+            Message.user("After."),
+          ],
+          providerOptions: { reasoningEffort: "xhigh" },
+        }),
+      )
+
+      expect(prepared.body.reasoning).toEqual({ effort: "medium" })
+      expect(prepared.body.input).toEqual([
+        { role: "user", content: [{ type: "input_text", text: "Before." }] },
+        { type: "configuration_update", reasoning: { effort: "xhigh" } },
+        { role: "user", content: [{ type: "input_text", text: "After." }] },
+      ])
+    }),
+  )
+
+  it.effect("omits reasoning.effort for the model default and sends `medium` for a switch back to it", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: astra,
+          messages: [
+            Message.user("One."),
+            Message.effort({ effort: "low" }),
+            Message.user("Two."),
+            Message.effort({ previous: "low" }),
+            Message.user("Three."),
+          ],
+        }),
+      )
+
+      expect(prepared.body.reasoning).toBeUndefined()
+      expect(updates(prepared.body)).toEqual([
+        { type: "configuration_update", reasoning: { effort: "low" } },
+        { type: "configuration_update", reasoning: { effort: "medium" } },
+      ])
+    }),
+  )
+
+  it.effect("falls back to a plain top-level effort when history drifted from the current effort", () =>
+    Effect.gen(function* () {
+      const drifted = yield* compileRequest(
+        LLM.request({ model: astra, messages: conversation, providerOptions: { reasoningEffort: "xhigh" } }),
+      )
+      const plain = yield* compileRequest(
+        LLM.request({
+          model: astra,
+          messages: [Message.user("Before."), Message.user("After.")],
+          providerOptions: { reasoningEffort: "xhigh" },
+        }),
+      )
+
+      expect(drifted.body).toEqual(plain.body)
+      expect(drifted.body.reasoning).toEqual({ effort: "xhigh" })
+    }),
+  )
+
+  it.effect("strips markers when automatic context management is enabled", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: astra,
+          messages: conversation,
+          providerOptions: { reasoningEffort: "low", contextManagement: [{ type: "compaction" }] },
+        }),
+      )
+
+      expect(updates(prepared.body)).toEqual([])
+      expect(prepared.body.reasoning).toEqual({ effort: "low" })
+      expect(prepared.body.context_management).toEqual([{ type: "compaction" }])
+    }),
+  )
+
+  for (const [id, supported] of [
+    ["gpt-6-astra", true],
+    ["openai/gpt-6-astra", true],
+    ["gpt-6-astra-2026-09-01", false],
+    ["gpt-5.6-sol", false],
+  ] as const) {
+    it.effect(`${supported ? "lowers" : "strips"} markers for ${id}`, () =>
+      Effect.gen(function* () {
+        const prepared = yield* compileRequest(
+          LLM.request({ model: openai(id), messages: conversation, providerOptions: { reasoningEffort: "low" } }),
+        )
+
+        expect(updates(prepared.body)).toHaveLength(supported ? 1 : 0)
+        expect(prepared.body.reasoning).toEqual({ effort: supported ? "high" : "low" })
+      }),
+    )
+  }
+
+  it.effect("honors the compatibility override in both directions", () =>
+    Effect.gen(function* () {
+      const enabled = yield* compileRequest(
+        LLM.request({
+          model: openai("gpt-5.5", { supportsEffortUpdates: true }),
+          messages: conversation,
+          providerOptions: { reasoningEffort: "low" },
+        }),
+      )
+      const disabled = yield* compileRequest(
+        LLM.request({
+          model: openai("gpt-6-astra", { supportsEffortUpdates: false }),
+          messages: conversation,
+          providerOptions: { reasoningEffort: "low" },
+        }),
+      )
+
+      expect(updates(enabled.body)).toHaveLength(1)
+      expect(updates(disabled.body)).toHaveLength(0)
+    }),
+  )
+
+  const checkpoint = { type: "compaction", id: "cmp_1", encrypted_content: "opaque" }
+  const compactRequest = LLM.request({
+    model: OpenAI.configure({ apiKey: "fixture" }).responses("gpt-6-astra"),
+    messages: conversation,
+    providerOptions: { reasoningEffort: "low" },
+  })
+
+  testEffect(
+    dynamicResponse(({ text, respond }) =>
+      Effect.sync(() => {
+        const body = JSON.parse(text)
+        expect(body.reasoning).toEqual({ effort: "high" })
+        expect(body.input).toEqual([
+          { role: "user", content: [{ type: "input_text", text: "Before." }] },
+          { type: "configuration_update", reasoning: { effort: "low" } },
+          { role: "user", content: [{ type: "input_text", text: "After." }] },
+          { type: "compaction_trigger" },
+        ])
+        return respond(sseEvents({ type: "response.completed", response: { id: "resp_1", output: [checkpoint] } }), {
+          headers: { "content-type": "text/event-stream" },
+        })
+      }),
+    ),
+  ).effect("keeps configuration updates in the checkpoint body", () =>
+    Effect.gen(function* () {
+      const result = yield* LLMClient.compact(compactRequest, { mechanism: "trigger" })
+      expect(result.checkpoint.encrypted).toBe("opaque")
+    }),
+  )
+
+  testEffect(
+    dynamicResponse(({ request, text, respond }) =>
+      Effect.sync(() => {
+        expect(new URL(request.url).pathname).toEndWith("/responses/compact")
+        expect(JSON.parse(text).input).toEqual([
+          { role: "user", content: [{ type: "input_text", text: "Before." }] },
+          { role: "user", content: [{ type: "input_text", text: "After." }] },
+        ])
+        return respond(JSON.stringify({ object: "response.compaction", output: [checkpoint] }))
+      }),
+    ),
+  ).effect("drops markers from the compaction endpoint body", () =>
+    Effect.gen(function* () {
+      const result = yield* LLMClient.compact(compactRequest, { mechanism: "endpoint" })
+      expect(result.replacement.map((message) => message.content[0]?.type)).toEqual(["compaction"])
+    }),
+  )
+})

packages/cli/src/acp/config-option.ts

@@ -76,7 +76,10 @@ export function buildEffortSelectOption(input: {
     category: "thought_level",
     type: "select",
     currentValue: selectVariant(input.currentVariant, input.variants),
-    options: input.variants.map((variant) => ({ value: variant, name: formatVariantName(variant) })),
+    options: [...new Set([...input.variants, DEFAULT_VARIANT_VALUE])].map((variant) => ({
+      value: variant,
+      name: formatVariantName(variant),
+    })),
   }
 }
 
@@ -125,6 +128,7 @@ export function formatVariantName(variant: string) {
 }
 
 function selectVariant(variant: string | undefined, variants: readonly string[]) {
+  if (!variant || variant === DEFAULT_VARIANT_VALUE) return DEFAULT_VARIANT_VALUE
   if (variant && variants.includes(variant)) return variant
   if (variants.includes(DEFAULT_VARIANT_VALUE)) return DEFAULT_VARIANT_VALUE
   return variants[0] ?? DEFAULT_VARIANT_VALUE

packages/cli/src/acp/event.ts

@@ -201,7 +201,7 @@ export async function streamTurn(input: {
         if (!child) assistantMessageID = event.data.assistantMessageID
         await send({
           sessionUpdate: "agent_thought_chunk",
-          messageId: event.data.assistantMessageID,
+          messageId: `${event.data.assistantMessageID}:reasoning:${event.data.ordinal}`,
           content: { type: "text", text: event.data.delta },
         })
         continue
@@ -455,6 +455,8 @@ async function replayMessage(
     return
   }
   if (message.type !== "assistant") return
+  // Live reasoning ordinals count only reasoning parts, not the mixed content array.
+  let reasoningOrdinal = 0
   for (const part of message.content) {
     if (part.type === "text") {
       await connection.sessionUpdate({
@@ -472,7 +474,7 @@ async function replayMessage(
         sessionId: sessionID,
         update: {
           sessionUpdate: "agent_thought_chunk",
-          messageId: message.id,
+          messageId: `${message.id}:reasoning:${reasoningOrdinal++}`,
           content: { type: "text", text: part.text },
         },
       })

packages/cli/src/acp/service.ts

@@ -41,7 +41,12 @@ import type {
 } from "@agentclientprotocol/sdk"
 import { OPENCODE_VERSION } from "../version"
 import { SessionMessage } from "@opencode/schema/session-message"
-import { buildConfigOptions, parseModelSelection, type ConfigOptionProvider } from "./config-option"
+import {
+  buildConfigOptions,
+  DEFAULT_VARIANT_VALUE,
+  parseModelSelection,
+  type ConfigOptionProvider,
+} from "./config-option"
 import { promptContentToParts } from "./content"
 import {
   ChildSessionUpdateMethod,
@@ -275,7 +280,7 @@ export function make(input: { readonly client: OpenCodeClient; readonly connecti
       if (typeof params.value !== "string") throw new ACPError.InvalidConfigOptionError({ configId: params.configId })
       switch (params.configId) {
         case "model": {
-          const selected = requireModel(state.catalog, params.value)
+          const selected = requireModel(state.catalog, params.value, state.model)
           state.model = selected
           await input.client.session.switchModel({ sessionID: state.id, model: selected })
           break
@@ -284,7 +289,10 @@ export function make(input: { readonly client: OpenCodeClient; readonly connecti
           const model = state.catalog.models.find(
             (item) => item.providerID === state.model.providerID && item.id === state.model.id,
           )
-          if (!model?.variants.some((variant) => variant.id === params.value))
+          if (
+            !model ||
+            (params.value !== DEFAULT_VARIANT_VALUE && !model.variants.some((variant) => variant.id === params.value))
+          )
             throw new ACPError.InvalidEffortError({ effort: params.value })
           state.model = { ...state.model, variant: params.value }
           await input.client.session.switchModel({ sessionID: state.id, model: state.model })
@@ -453,7 +461,7 @@ function providers(models: readonly ModelInfo[]): ConfigOptionProvider[] {
     }))
 }
 
-function requireModel(catalog: Catalog, modelID: string): ModelRef {
+function requireModel(catalog: Catalog, modelID: string, current: ModelRef): ModelRef {
   const selected = parseModelSelection(modelID, catalog.providers)
   const model = catalog.models.find(
     (item) => item.providerID === selected.model.providerID && item.id === selected.model.modelID,
@@ -461,7 +469,14 @@ function requireModel(catalog: Catalog, modelID: string): ModelRef {
   if (!model) throw new ACPError.InvalidModelError({ providerId: selected.model.providerID, modelId: modelID })
   if (selected.variant && !model.variants.some((variant) => variant.id === selected.variant))
     throw new ACPError.InvalidEffortError({ effort: selected.variant })
-  return { providerID: model.providerID, id: model.id, variant: selected.variant }
+  const variant =
+    selected.variant ??
+    (current.providerID === model.providerID &&
+    current.id === model.id &&
+    (current.variant === DEFAULT_VARIANT_VALUE || model.variants.some((variant) => variant.id === current.variant))
+      ? current.variant
+      : undefined)
+  return { providerID: model.providerID, id: model.id, variant }
 }
 
 async function selectMode(client: OpenCodeClient, state: Attached, modeID: string) {

packages/cli/test/acp/config-options.subprocess.test.ts

@@ -50,11 +50,11 @@ describe("acp config option subprocess", () => {
     const effort = requireSelectOption((await newSession(acp, fixture.home)).configOptions, "effort")
 
     expect(effort.category).toBe("thought_level")
-    expect(effort.currentValue).toBe("low")
-    expect(flattenSelectOptions(effort).map((option) => option.value)).toEqual(["low", "high"])
+    expect(effort.currentValue).toBe("default")
+    expect(flattenSelectOptions(effort).map((option) => option.value)).toEqual(["low", "high", "default"])
   }, 60_000)
 
-  test("effort switch updates currentValue", async () => {
+  test("effort survives model synchronization and can be reset to default", async () => {
     await using fixture = await createAcpFixture()
     const acp = fixture.spawn()
     await initialize(acp)
@@ -70,5 +70,23 @@ describe("acp config option subprocess", () => {
     )
 
     expect(selectConfigOption(updated.configOptions, "effort")?.currentValue).toBe(nextEffort)
+
+    const synchronized = expectOk(
+      await acp.request<SetSessionConfigOptionResponse>("session/set_config_option", {
+        sessionId: session.sessionId,
+        configId: "model",
+        value: requireSelectOption(session.configOptions, "model").currentValue,
+      }),
+    )
+    expect(selectConfigOption(synchronized.configOptions, "effort")?.currentValue).toBe(nextEffort)
+
+    const reset = expectOk(
+      await acp.request<SetSessionConfigOptionResponse>("session/set_config_option", {
+        sessionId: session.sessionId,
+        configId: "effort",
+        value: "default",
+      }),
+    )
+    expect(selectConfigOption(reset.configOptions, "effort")?.currentValue).toBe("default")
   }, 60_000)
 })

packages/cli/test/acp/event-behavior.test.ts

@@ -91,7 +91,7 @@ describe("acp event behavior", () => {
     }
   })
 
-  test("preserves text and reasoning order before returning the terminal response", async () => {
+  test("preserves reasoning boundaries and update order during streaming and replay", async () => {
     const firstUpdate = Promise.withResolvers<void>()
     const releaseUpdate = Promise.withResolvers<void>()
     const allUpdates = Promise.withResolvers<void>()
@@ -108,6 +108,14 @@ describe("acp event behavior", () => {
             delta: "think-1",
           }),
         )
+        send(
+          ephemeralEvent("session.reasoning.delta", {
+            sessionID: "ses_order",
+            assistantMessageID: "msg_order",
+            ordinal: 0,
+            delta: " continued",
+          }),
+        )
         send(
           ephemeralEvent("session.text.delta", {
             sessionID: "ses_order",
@@ -120,7 +128,7 @@ describe("acp event behavior", () => {
           ephemeralEvent("session.reasoning.delta", {
             sessionID: "ses_order",
             assistantMessageID: "msg_order",
-            ordinal: 2,
+            ordinal: 1,
             delta: "think-2",
           }),
         )
@@ -144,7 +152,7 @@ describe("acp event behavior", () => {
           firstUpdate.resolve()
           await releaseUpdate.promise
         }
-        if (updates.length === 3) allUpdates.resolve()
+        if (updates.length === 4) allUpdates.resolve()
       },
       requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
     } satisfies Connection
@@ -171,18 +179,48 @@ describe("acp event behavior", () => {
           ) {
             return [
               item.update.sessionUpdate,
+              item.update.messageId,
               item.update.content.type === "text" ? item.update.content.text : undefined,
             ]
           }
           return [item.update.sessionUpdate, undefined]
         }),
       ).toEqual([
-        ["agent_thought_chunk", "think-1"],
-        ["agent_message_chunk", "answer"],
-        ["agent_thought_chunk", "think-2"],
+        ["agent_thought_chunk", "msg_order:reasoning:0", "think-1"],
+        ["agent_thought_chunk", "msg_order:reasoning:0", " continued"],
+        ["agent_message_chunk", "msg_order", "answer"],
+        ["agent_thought_chunk", "msg_order:reasoning:1", "think-2"],
       ])
       expect(fixture.requests.at(-1)?.path).toBe("/api/session/ses_order/message/msg_order")
       expect(response).toMatchObject({ stopReason: "end_turn", usage: { totalTokens: 2 } })
+
+      const replayed: SessionUpdateParams[] = []
+      await replayMessages(recordingConnection(replayed), "ses_order", "/workspace", [
+        {
+          id: "msg_order",
+          type: "assistant",
+          agent: "build",
+          model: { providerID: "test", id: "test-model" },
+          time: { created: 1 },
+          content: [
+            { type: "reasoning", text: "think-1 continued" },
+            { type: "text", text: "answer" },
+            { type: "reasoning", text: "think-2" },
+          ],
+        },
+      ])
+      expect(replayed).toEqual([
+        {
+          sessionId: "ses_order",
+          update: {
+            sessionUpdate: "agent_thought_chunk",
+            messageId: "msg_order:reasoning:0",
+            content: { type: "text", text: "think-1 continued" },
+          },
+        },
+        updates[2],
+        updates[3],
+      ])
     } finally {
       releaseUpdate.resolve()
       releaseSubmit.resolve()

packages/cli/test/acp/service-directory.test.ts

@@ -222,7 +222,7 @@ describe("acp service directory behavior", () => {
     await fixture.service.setSessionMode({ sessionId: session.sessionId, modeId: "build" })
 
     expect(currentValue(selectedModel, "model")).toBe("test/second-model")
-    expect(currentValue(selectedModel, "effort")).toBe("low")
+    expect(currentValue(selectedModel, "effort")).toBe("default")
     expect(currentValue(selectedEffort, "effort")).toBe("medium")
     expect(currentValue(selectedMode, "mode")).toBe("plan")
     expect(

packages/cli/test/acp/service-lifecycle.test.ts

@@ -32,7 +32,7 @@ describe("acp service lifecycle", () => {
         model: { providerID: "test", id: "second-model" },
       },
     })
-    expect(currentValue(created, "effort")).toBe("none")
+    expect(currentValue(created, "effort")).toBe("default")
   })
 
   test("loads and forks with paginated replay while resume does not replay", async () => {

packages/core/src/aisdk.ts

@@ -547,6 +547,14 @@ function assistantPart(part: ContentPart): AssistantContent {
       ]
     case "tool-result":
       return toolResultPart(part)
+    case "effort":
+      throw ProviderShared.unsupportedContent("AI SDK", "assistant", [
+        "text",
+        "media",
+        "reasoning",
+        "tool-call",
+        "tool-result",
+      ])
   }
 }
 

packages/core/src/session/compaction.ts

@@ -196,6 +196,7 @@ const estimateMedia = (mime: string) => {
 const estimatePart = (part: ContentPart): number => {
   // Encrypted checkpoints have no locally measurable token size.
   if (part.type === "compaction") return Token.estimate(part.text ?? "")
+  if (part.type === "effort") return 0
   if (part.type === "text" || part.type === "reasoning") return Token.estimate(part.text)
   if (part.type === "media") return estimateMedia(part.mediaType)
   if (part.type === "tool-call") return Token.estimate(part.name + (JSON.stringify(part.input) ?? ""))

packages/core/src/session/runner/to-llm-message.ts

@@ -1,4 +1,11 @@
-import { Message, ToolCallPart, ToolResultPart, type ContentPart, type ProviderMetadata } from "@opencode/ai"
+import {
+  Message,
+  ReasoningEfforts,
+  ToolCallPart,
+  ToolResultPart,
+  type ContentPart,
+  type ProviderMetadata,
+} from "@opencode/ai"
 import type { Model } from "@opencode/schema/model"
 import { Option, Schema } from "effect"
 import { fileURLToPath } from "url"
@@ -222,11 +229,31 @@ const assistant = (message: SessionMessage.Assistant, model: Model.Ref, provider
   ]
 }
 
+const EFFORT_VARIANTS = new Set<string>(ReasoningEfforts)
+
+// Budget and toggle variants reuse these names; the protocol's drift check catches ones that are not effort options.
+const variantEffort = (variant: Model.VariantID | undefined) => {
+  if (variant === undefined || variant === "default") return { effort: undefined }
+  return EFFORT_VARIANTS.has(variant) ? { effort: variant } : undefined
+}
+
+const modelSwitched = (message: SessionMessage.ModelSelected, model: Model.Ref): Message[] => {
+  const previous = message.previous
+  if (previous === undefined) return []
+  const same = (ref: Model.Ref) => ref.providerID === model.providerID && ref.id === model.id
+  if (!same(message.model) || !same(previous)) return []
+  const to = variantEffort(message.model.variant)
+  const from = variantEffort(previous.variant)
+  if (to === undefined || from === undefined) return []
+  return [Message.effort({ effort: to.effort, previous: from.effort })]
+}
+
 function toLLMMessage(message: SessionMessage.Info, model: Model.Ref, providerMetadataKey: string): Message[] {
   switch (message.type) {
     case "agent-switched":
-    case "model-switched":
       return []
+    case "model-switched":
+      return modelSwitched(message, model)
     case "location-switched":
       return [
         Message.make({

packages/core/test/session-runner-message.test.ts

@@ -202,6 +202,44 @@ Recent work
     ])
   })
 
+  describe("model-switched", () => {
+    const ref = (variant?: string) =>
+      Model.Ref.make({
+        id: Model.ID.make("model"),
+        providerID: Provider.ID.make("provider"),
+        ...(variant === undefined ? {} : { variant: Model.VariantID.make(variant) }),
+      })
+    const switched = (to: Model.Ref, previous?: Model.Ref) =>
+      SessionMessage.ModelSelected.make({
+        id: id("model"),
+        type: "model-switched",
+        model: to,
+        previous,
+        time: { created },
+      })
+
+    test("records a same-model effort switch as an effort update", () => {
+      expect(toLLMMessages([switched(ref("low"), ref("high"))], ref("low"))).toEqual([
+        Message.effort({ effort: "low", previous: "high" }),
+      ])
+    })
+
+    test("maps the default variant and no variant to the model default effort", () => {
+      expect(toLLMMessages([switched(ref("low"), ref())], ref("low"))).toEqual([Message.effort({ effort: "low" })])
+      expect(toLLMMessages([switched(ref("default"), ref("max"))], ref())).toEqual([
+        Message.effort({ previous: "max" }),
+      ])
+    })
+
+    test("ignores switches that are not effort changes on the requested model", () => {
+      const other = Model.Ref.make({ id: Model.ID.make("other"), providerID: Provider.ID.make("provider") })
+      expect(toLLMMessages([switched(ref("low"))], ref("low"))).toEqual([])
+      expect(toLLMMessages([switched(ref("low"), other)], ref("low"))).toEqual([])
+      expect(toLLMMessages([switched(ref("thinking"), ref("high"))], ref("thinking"))).toEqual([])
+      expect(toLLMMessages([switched(ref("low"), ref("high"))], other)).toEqual([])
+    })
+  })
+
   test("lowers text attachments after the prompt in one user message", () => {
     const file = FileAttachment.make({
       data: Base64.make(Buffer.from("export const value = 1").toString("base64")),

packages/core/test/session-runner.test.ts

@@ -1996,6 +1996,39 @@ describe("SessionRunnerLLM", () => {
     yield* s.runPrompt("Fourth")
   })
 
+  scenario("records a same-model effort switch as a cache-preserving effort update", function* (s) {
+    s.currentModel = LanguageModel.make({ id: "claude-opus-5", provider: "anthropic", route: AnthropicMessages.route })
+    const model = { id: ID.make("claude-opus-5"), providerID: Provider.ID.make("anthropic") }
+    yield* s.bus.publish(SessionEvent.ModelSelected, {
+      sessionID,
+      model: { ...model, variant: Model.VariantID.make("high") },
+    })
+    yield* s.llm.push(TestLLM.text("Earlier answer", "text-effort-high"))
+    yield* s.runPrompt("First")
+    yield* s.bus.publish(SessionEvent.ModelSelected, {
+      sessionID,
+      model: { ...model, variant: Model.VariantID.make("low") },
+    })
+    // The selected variant reaches the request as the provider effort option.
+    s.currentModel = LanguageModel.update(s.currentModel, { defaults: { providerOptions: { effort: "low" } } })
+    yield* s.llm.push(TestLLM.text("Later answer", "text-effort-low"))
+    yield* s.runPrompt("Second")
+
+    expect(messageRoles(s.requests[1])).toEqual(["user", "assistant", "system", "user"])
+    expect(s.requests[1]?.messages[2]).toEqual(Message.effort({ effort: "low", previous: "high" }))
+
+    const compiled = yield* compileRequest(s.requests[1]!)
+    expect(compiled.body).toMatchObject({
+      output_config: { effort: "high" },
+      messages: [
+        { role: "user" },
+        { role: "assistant" },
+        { role: "system", content: [], output_config: { effort: "low" } },
+        { role: "user" },
+      ],
+    })
+  })
+
   scenario("preserves instruction values while a source is temporarily unavailable", function* (s) {
     yield* s.runPrompt("First")
     yield* s.bus.publish(SessionEvent.ModelSelected, {

services/www/src/docs/content/build/plugins/effect.mdx

@@ -1099,7 +1099,7 @@ effect: (ctx) =>
     const session = ctx.session
     yield* session.hook("context", (event) =>
       Effect.sync(() => {
-        event.system.push({ text: "Keep the review focused on correctness." })
+        event.system.push({ type: "text", text: "Keep the review focused on correctness." })
         delete event.tools.write
       }),
     )

services/www/src/docs/content/build/plugins/index.mdx

@@ -1222,7 +1222,7 @@ differently:
 
 ```ts
 await ctx.session.hook("context", (event) => {
-  event.system.push({ text: "Keep the review focused on correctness." })
+  event.system.push({ type: "text", text: "Keep the review focused on correctness." })
   delete event.tools.write
   event.options.temperature = 0.2
   event.options.maxTokens = 8_000