The best way to control Claude Code, Codex and more from any computer or phone
fix(acp): explain rejected model selections (#19699)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Julius Marminge <julius0216@outlook.com>
Wout Stiens committed
Oct 20, 2026 at 08:18 UTC
04ab2fca4bcb07b1af609686ad697a22e5687d8a
4 files changed
+276
-23
apps/server/src/orchestration-v2/ProviderTurnStartService.ts
+7
-3
@@ -47,7 +47,10 @@ import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter"
47
import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
48
import * as ProjectionStore from "./ProjectionStore.ts";
49
import * as ProviderSessionManager from "./ProviderSessionManager.ts";
50
-import { makeProviderFailure } from "@t3tools/provider-core/server/failure";
50
+import {
51
+ knownProviderFailureMessage,
52
+ makeProviderFailure,
53
+} from "@t3tools/provider-core/server/failure";
54
import * as RunExecutionService from "./RunExecutionService.ts";
55
import * as RuntimePolicy from "./RuntimePolicy.ts";
56
import {
@@ -569,11 +572,12 @@ export const layer: Layer.Layer<
572
failure: makeProviderFailure({
573
cause: failed.error,
574
message:
572
- nestedCause instanceof Error
575
+ knownProviderFailureMessage(failed.error) ??
576
+ (nestedCause instanceof Error
577
? nestedCause.message
578
: typeof nestedCause === "string"
579
? nestedCause
576
- : failed.error.message,
580
+ : failed.error.message),
581
class: "provider_error",
582
}),
583
},
apps/server/src/orchestration-v2/testkit/OrchestratorReplayFixtures.integration.test.ts
+195
-4
@@ -1,13 +1,23 @@
1
import * as NodeServices from "@effect/platform-node/NodeServices";
2
import { assert, describe, it } from "@effect/vitest";
3
-import type {
4
- OrchestrationV2DomainEvent,
5
- ProviderReplayEntry,
6
- ProviderReplayTranscript,
3
+import {
4
+ ProviderDriverKind,
5
+ ProviderInstanceId,
6
+ type OrchestrationV2DomainEvent,
7
+ type ProviderReplayEntry,
8
+ type ProviderReplayTranscript,
9
} from "@t3tools/contracts";
10
+import * as DateTime from "effect/DateTime";
11
import * as Effect from "effect/Effect";
12
import * as FileSystem from "effect/FileSystem";
13
+import * as Layer from "effect/Layer";
14
+import * as Option from "effect/Option";
15
import * as Path from "effect/Path";
16
+import * as Stream from "effect/Stream";
17
+import { TestClock } from "effect/testing";
18
+
19
+import * as EffectWorker from "../EffectWorker.ts";
20
+import * as Orchestrator from "../Orchestrator.ts";
21
22
import { ClaudeOrchestratorReplayHarness } from "../Adapters/ClaudeAdapterV2.testkit.ts";
23
import { CodexOrchestratorReplayHarness } from "../Adapters/CodexAdapterV2.testkit.ts";
@@ -31,12 +41,14 @@ import { messageRestartInput } from "./fixtures/message_steering/input.ts";
41
import {
42
assertProviderNativeSubagentRootTurns,
43
materializeFixtureInput,
44
+ SIMPLE_PROMPT,
45
projectionFor,
46
type OrchestratorFixtureInput,
47
type ProviderOrchestratorReplayVariant,
48
} from "./fixtures/shared.ts";
49
import {
50
runOrchestratorV2ProviderReplayScenario,
51
+ layerProviderReplay,
52
type OrchestratorV2ProviderReplayHarness,
53
} from "./ProviderReplayHarness.ts";
54
import { checkpointWorkspace } from "@t3tools/provider-testing/replayWorkspace";
@@ -232,6 +244,185 @@ function runFixtureProviderWithRegisteredHarness(input: {
244
}
245
246
describe("orchestrator replay fixtures", () => {
247
+ it.effect.each([
248
+ { name: "open", firstTurn: false, code: -32602 },
249
+ { name: "switch", firstTurn: true, code: -32602 },
250
+ { name: "authentication", firstTurn: false, code: -32000 },
251
+ ])("preserves the ACP model-write $name failure through orchestration", (testCase) =>
252
+ Effect.gen(function* () {
253
+ const name = `acp_model_write_${testCase.name}`;
254
+ const sessionId = "grok-replay-session-1";
255
+ const rejectedModel = "replay-model-b";
256
+ const modelSelection = {
257
+ instanceId: ProviderInstanceId.make("acpRegistry"),
258
+ model: rejectedModel,
259
+ };
260
+ const recorded = yield* readTranscript(
261
+ new URL("./fixtures/simple/registry_transcript.ndjson", import.meta.url),
262
+ );
263
+ const sessionIndex = recorded.entries.findIndex(
264
+ (entry) => "label" in entry && entry.label === "session.created",
265
+ );
266
+ assert.isAtLeast(sessionIndex, 0);
267
+ const transcript = {
268
+ ...recorded,
269
+ scenario: name,
270
+ entries: [
271
+ ...recorded.entries.slice(0, sessionIndex),
272
+ {
273
+ type: "emit_inbound",
274
+ label: "session.created",
275
+ frame: {
276
+ kind: "response",
277
+ method: "session/new",
278
+ result: {
279
+ sessionId,
280
+ configOptions: [
281
+ {
282
+ id: "model",
283
+ name: "Model",
284
+ category: "model",
285
+ type: "select",
286
+ currentValue: "replay-model-a",
287
+ options: [
288
+ { value: "replay-model-a", name: "Model A" },
289
+ { value: rejectedModel, name: "Model B" },
290
+ ],
291
+ },
292
+ ],
293
+ },
294
+ },
295
+ },
296
+ ...(testCase.firstTurn
297
+ ? recorded.entries
298
+ .slice(sessionIndex + 1)
299
+ .filter((entry) => entry.type !== "runtime_exit")
300
+ : []),
301
+ {
302
+ type: "expect_outbound",
303
+ label: "session.set_model",
304
+ frame: {
305
+ kind: "request",
306
+ method: "session/set_config_option",
307
+ params: { sessionId, configId: "model", value: rejectedModel },
308
+ },
309
+ },
310
+ {
311
+ type: "emit_inbound",
312
+ label: "session.set_model.rejected",
313
+ frame: {
314
+ kind: "response",
315
+ method: "session/set_config_option",
316
+ error: {
317
+ code: testCase.code,
318
+ message: testCase.code === -32602 ? "Invalid provider" : "Authentication required",
319
+ },
320
+ },
321
+ },
322
+ ],
323
+ } satisfies ProviderReplayTranscript;
324
+ const materialized = yield* materializeFixtureInput({
325
+ scenario: name,
326
+ fixtureInput: {
327
+ steps: Array.from({ length: testCase.firstTurn ? 2 : 1 }, () => ({
328
+ type: "message" as const,
329
+ text: SIMPLE_PROMPT,
330
+ })),
331
+ },
332
+ driver: ProviderDriverKind.make("acpRegistry"),
333
+ modelSelection: {
334
+ ...modelSelection,
335
+ model: testCase.firstTurn ? "replay-model-a" : rejectedModel,
336
+ },
337
+ });
338
+ const scenario = {
339
+ ...materialized,
340
+ name,
341
+ transcript: yield* AcpRegistryOrchestratorReplayHarness.decodeTranscript(
342
+ materializeReplayTranscriptRuntimeInstructions(transcript, {
343
+ driver: ProviderDriverKind.make("acpRegistry"),
344
+ model: "replay-model-a",
345
+ }),
346
+ ),
347
+ runtimePolicyOverride: { cwd: yield* checkpointWorkspace(name) },
348
+ };
349
+ yield* Effect.gen(function* () {
350
+ const orchestrator = yield* Orchestrator.OrchestratorV2;
351
+ const worker = yield* EffectWorker.OrchestrationEffectWorkerV2;
352
+ if (testCase.firstTurn) yield* EffectWorker.runDaemon.pipe(Effect.forkScoped);
353
+ for (const [index, command] of materialized.commands.entries()) {
354
+ const isFirstTurn =
355
+ testCase.firstTurn && command.type === "message.dispatch" && index === 1;
356
+ yield* orchestrator.dispatch(
357
+ command.type === "message.dispatch" && !isFirstTurn
358
+ ? { ...command, modelSelection }
359
+ : command,
360
+ );
361
+ if (isFirstTurn) {
362
+ // Wait for the committed terminal event before switching models.
363
+ yield* orchestrator.streamStoredEvents.pipe(
364
+ Stream.filter(
365
+ ({ event }) => event.type === "run.updated" && event.payload.status === "completed",
366
+ ),
367
+ Stream.runHead,
368
+ );
369
+ }
370
+ }
371
+ if (testCase.firstTurn) {
372
+ yield* orchestrator.streamStoredEvents.pipe(
373
+ Stream.filter(
374
+ ({ event }) => event.type === "run.updated" && event.payload.status === "failed",
375
+ ),
376
+ Stream.runHead,
377
+ );
378
+ } else {
379
+ // Failed opens retry on the outbox schedule. Advance to each recorded
380
+ // deadline, draining effects instead of polling the projection.
381
+ for (let attempt = 0; attempt < 10; attempt++) {
382
+ yield* worker.drain();
383
+ const next = yield* worker.nextClaimableAt;
384
+ if (Option.isNone(next)) break;
385
+ const now = yield* DateTime.now;
386
+ yield* TestClock.adjust(
387
+ Math.max(0, DateTime.toEpochMillis(next.value) - DateTime.toEpochMillis(now)),
388
+ );
389
+ }
390
+ }
391
+ const projection = yield* orchestrator.getThreadProjection(
392
+ materialized.projectionThreadIds[0]!,
393
+ );
394
+ assert.deepEqual(
395
+ projection.runs.map((run) => run.status),
396
+ testCase.firstTurn ? ["completed", "failed"] : ["failed"],
397
+ );
398
+ const errors = projection.turnItems.filter((item) => item.type === "error");
399
+ assert.lengthOf(errors, 1);
400
+ assert.equal(errors[0]?.failure.class, "provider_error");
401
+ if (testCase.code === -32602) {
402
+ assert.equal(
403
+ errors[0]?.failure.message,
404
+ 'The agent did not accept the model "replay-model-b". Choose another model for this provider, then retry.',
405
+ );
406
+ } else {
407
+ assert.match(
408
+ errors[0]?.failure.message ?? "",
409
+ /^Failed to open acpRegistry provider session \S+\.$/u,
410
+ );
411
+ }
412
+ }).pipe(
413
+ Effect.provide(
414
+ layerProviderReplay(scenario, AcpRegistryOrchestratorReplayHarness, {
415
+ runEffectWorker: false,
416
+ }),
417
+ ),
418
+ );
419
+ }).pipe(
420
+ Effect.scoped,
421
+ provideDeterministicTestRuntime,
422
+ Effect.provide(Layer.merge(IdAllocator.layer, NodeServices.layer)),
423
+ ),
424
+ );
425
+
426
it.effect.each(
427
ORCHESTRATOR_REPLAY_FIXTURES.flatMap((fixture) =>
428
fixture.providers.map(
packages/provider-acp/src/server/adapter.ts
+38
-7
@@ -51,6 +51,7 @@ import * as Option from "effect/Option";
51
import * as Queue from "effect/Queue";
52
import * as Ref from "effect/Ref";
53
import * as Result from "effect/Result";
54
+import * as Schema from "effect/Schema";
55
import * as Scope from "effect/Scope";
56
import * as Semaphore from "effect/Semaphore";
57
import * as Stream from "effect/Stream";
@@ -204,6 +205,24 @@ export interface AcpAdapterV2ExtensionContext {
205
readonly lastProposedPlanMarkdown: Effect.Effect<string | undefined>;
206
}
207
208
+/**
209
+ * Raised when an agent does not accept the session's model selection: the
210
+ * session's model option does not offer it, or the agent answers the write
211
+ * with invalid params. `makeProviderFailure` shows its message to the user;
212
+ * the agent's reply stays on `cause`.
213
+ */
214
+class AcpModelSelectionError extends Schema.TaggedError<AcpModelSelectionError>()(
215
+ "AcpModelSelectionError",
216
+ {
217
+ model: Schema.String,
218
+ cause: Schema.Defect(),
219
+ },
220
+) {
221
+ override get message(): string {
222
+ return `The agent did not accept the model "${this.model}". Choose another model for this provider, then retry.`;
223
+ }
224
+}
225
+
226
export interface AcpAdapterV2Flavor {
227
readonly promptFailure?: (cause: unknown) => OrchestrationV2ProviderFailure;
228
readonly driver: ProviderDriverKind;
@@ -6610,13 +6629,23 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
6629
) {
6630
yield* Ref.set(activeSelection, null);
6631
const requestedModel = flavor.resolveModelId?.(modelSelection) ?? modelSelection.model;
6632
+ // Invalid params is the agent refusing the value, and the runtime
6633
+ // raises the same code when the session's model option does not offer
6634
+ // it. Other failures, such as sign-in or a lost connection, keep their
6635
+ // own error.
6636
+ const rejectedModel = (error: EffectAcpErrors.AcpError) =>
6637
+ error._tag === "AcpRequestError" && error.code === -32602
6638
+ ? new AcpModelSelectionError({ model: modelSelection.model, cause: error })
6639
+ : error;
6640
let appliedModel: string | undefined;
6641
if (flavor.applyModelSelection !== undefined) {
6615
- appliedModel = yield* flavor.applyModelSelection({
6616
- runtime,
6617
- startResult,
6618
- modelSelection,
6619
- });
6642
+ appliedModel = yield* flavor
6643
+ .applyModelSelection({
6644
+ runtime,
6645
+ startResult,
6646
+ modelSelection,
6647
+ })
6648
+ .pipe(Effect.mapError(rejectedModel));
6649
} else if (requestedModel.length > 0) {
6650
// Stored catalog choices can expire; explicitly configured custom IDs
6651
// are validated by the agent instead.
@@ -6632,7 +6661,9 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
6661
: entry.options.some((choice) => choice.value === requestedModel),
6662
)
6663
) {
6635
- yield* runtime.setConfigOption(modelOption.id, requestedModel);
6664
+ yield* runtime
6665
+ .setConfigOption(modelOption.id, requestedModel)
6666
+ .pipe(Effect.mapError(rejectedModel));
6667
appliedModel = requestedModel;
6668
}
6669
} else if (
@@ -6641,7 +6672,7 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
6672
modelState.availableModels.some((model) => model.modelId === requestedModel))
6673
) {
6674
if (modelState.currentModelId !== requestedModel) {
6644
- yield* runtime.setSessionModel(requestedModel);
6675
+ yield* runtime.setSessionModel(requestedModel).pipe(Effect.mapError(rejectedModel));
6676
}
6677
appliedModel = requestedModel;
6678
}
packages/provider-core/src/server/failure.ts
+36
-9
@@ -57,10 +57,24 @@ const PROVIDER_FAILURE_REASONS: Record<ProviderAdapterFailureReason, string> = {
57
attachment_unreadable: "an attachment could not be read",
58
};
59
60
-function causeMessage(cause: unknown): string | undefined {
60
+/**
61
+ * Walks a cause chain for curated text without reading arbitrary provider
62
+ * defect text. `known` is the message of a domain error T3 raised itself;
63
+ * `category` is the generic message of the innermost provider wrapper seen.
64
+ */
65
+function curatedCauseMessages(cause: unknown): {
66
+ readonly known: string | undefined;
67
+ readonly category: string | undefined;
68
+} {
69
const seen = new Set<unknown>();
70
let category: (typeof PROVIDER_FAILURE_CATEGORIES)[string];
71
let reason: string | undefined;
72
+ const categoryMessage = () => {
73
+ if (category === undefined) return undefined;
74
+ return reason
75
+ ? `${category.summary}: ${reason}. ${category.guidance}`
76
+ : `${category.summary}. ${category.guidance}`;
77
+ };
78
for (let depth = 0; depth < 16 && cause != null && !seen.has(cause); depth++) {
79
seen.add(cause);
80
try {
@@ -72,14 +86,19 @@ function causeMessage(cause: unknown): string | undefined {
86
const tag = (cause as Record<string, unknown>)._tag;
87
switch (tag) {
88
case "ContextHandoffBudgetError":
75
- return new ContextHandoffBudgetError().message;
89
+ return { known: new ContextHandoffBudgetError().message, category: categoryMessage() };
90
+ case "AcpModelSelectionError":
91
case "ClaudeBackgroundWorkBlocksQueryReplacementError":
92
case "ClaudeAppendSystemPromptFileError":
93
case "ClaudeAppendSystemPromptMissingValueError":
94
case "CursorModelUnavailableError":
80
- return stringField(cause, "message");
95
+ return { known: stringField(cause, "message"), category: categoryMessage() };
96
case "ContextHandoffDeliveryUncertainError":
82
- return "T3 could not confirm whether conversation history reached the provider. Retry the turn to recover the session.";
97
+ return {
98
+ known:
99
+ "T3 could not confirm whether conversation history reached the provider. Retry the turn to recover the session.",
100
+ category: categoryMessage(),
101
+ };
102
case "ProviderAdapterProtocolError": {
103
const typedReason = (cause as Record<string, unknown>).reason;
104
if (
@@ -101,10 +120,16 @@ function causeMessage(cause: unknown): string | undefined {
120
break;
121
}
122
}
104
- if (category === undefined) return undefined;
105
- return reason
106
- ? `${category.summary}: ${reason}. ${category.guidance}`
107
- : `${category.summary}. ${category.guidance}`;
123
+ return { known: undefined, category: categoryMessage() };
124
+}
125
+
126
+/**
127
+ * The curated message of a domain error in a failure's cause chain, if any.
128
+ * Callers that pass their own `message` to `makeProviderFailure` check it
129
+ * first, so a known reason is not hidden behind a wrapper's text.
130
+ */
131
+export function knownProviderFailureMessage(cause: unknown): string | undefined {
132
+ return curatedCauseMessages(cause).known;
133
}
134
135
function stringField(value: unknown, key: "message" | "code"): string | undefined {
@@ -183,7 +208,9 @@ export function makeProviderFailure(input: {
208
readonly retryable?: boolean | null;
209
readonly resetAt?: string | null;
210
}): OrchestrationV2ProviderFailure {
186
- const rawMessage = input.message ?? causeMessage(input.cause) ?? DEFAULT_PROVIDER_FAILURE_MESSAGE;
211
+ const curated = curatedCauseMessages(input.cause);
212
+ const rawMessage =
213
+ input.message ?? curated.known ?? curated.category ?? DEFAULT_PROVIDER_FAILURE_MESSAGE;
214
const message = boundedText(rawMessage, MAX_PROVIDER_FAILURE_MESSAGE_LENGTH);
215
const rawCode = input.code ?? stringField(input.cause, "code") ?? null;
216
const code =