Skip to content

Commit ef51c0d

Browse files
committed
feat(server,contracts): add Claude advisor model setting
Claude Code can consult a stronger model mid-turn through its advisor tool, but T3 Code had no way to turn it on, and a consult that did run (from the user's own Claude settings) rendered as a generic "Tool call" that spun until the end of the turn. The advisor is a server-side tool: its result arrives in the assistant stream as an `advisor_tool_result` block, never as a `tool_result` user message, so nothing ever closed the item. Adds an "Advisor model" field to the Claude provider settings and passes it to the Agent SDK as the `advisorModel` settings key. Completes the advisor item on its own result block, and titles it "Advisor consult" instead of the generic tool-call label. Written by Claude Opus 5 in Claude Code.
1 parent 5f878d2 commit ef51c0d

8 files changed

Lines changed: 263 additions & 5 deletions

File tree

‎apps/server/src/provider/Layers/ClaudeAdapter.test.ts‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -476,6 +476,130 @@ describe("ClaudeAdapterLive", () => {
476476
);
477477
});
478478

479+
it.effect("passes the configured advisor model to Claude", () => {
480+
const harness = makeHarness({ claudeConfig: { advisorModel: "opus" } });
481+
return Effect.gen(function* () {
482+
const adapter = yield* ClaudeAdapter;
483+
yield* adapter.startSession({
484+
threadId: THREAD_ID,
485+
provider: ProviderDriverKind.make("claudeAgent"),
486+
runtimeMode: "full-access",
487+
});
488+
489+
const options = harness.getLastCreateQueryInput()?.options;
490+
assert.deepEqual(options?.settings, { advisorModel: "opus" });
491+
}).pipe(
492+
Effect.provideService(Random.Random, makeDeterministicRandomService()),
493+
Effect.provide(harness.layer),
494+
);
495+
});
496+
497+
it.effect("omits the advisor model when the setting is empty", () => {
498+
const harness = makeHarness();
499+
return Effect.gen(function* () {
500+
const adapter = yield* ClaudeAdapter;
501+
yield* adapter.startSession({
502+
threadId: THREAD_ID,
503+
provider: ProviderDriverKind.make("claudeAgent"),
504+
runtimeMode: "full-access",
505+
});
506+
507+
const options = harness.getLastCreateQueryInput()?.options;
508+
assert.equal(options?.settings, undefined);
509+
}).pipe(
510+
Effect.provideService(Random.Random, makeDeterministicRandomService()),
511+
Effect.provide(harness.layer),
512+
);
513+
});
514+
515+
it.effect("completes the advisor item when the advisor result block arrives", () => {
516+
const harness = makeHarness();
517+
return Effect.gen(function* () {
518+
const adapter = yield* ClaudeAdapter;
519+
520+
const runtimeEventsFiber = yield* Stream.take(adapter.streamEvents, 7).pipe(
521+
Stream.runCollect,
522+
Effect.forkChild,
523+
);
524+
525+
const session = yield* adapter.startSession({
526+
threadId: THREAD_ID,
527+
provider: ProviderDriverKind.make("claudeAgent"),
528+
runtimeMode: "full-access",
529+
});
530+
531+
yield* adapter.sendTurn({
532+
threadId: session.threadId,
533+
input: "hello",
534+
attachments: [],
535+
});
536+
537+
harness.query.emit({
538+
type: "stream_event",
539+
session_id: "sdk-session-1",
540+
uuid: "stream-0",
541+
parent_tool_use_id: null,
542+
event: {
543+
type: "content_block_start",
544+
index: 0,
545+
content_block: {
546+
type: "server_tool_use",
547+
id: "srvtoolu-advisor-1",
548+
name: "advisor",
549+
input: {},
550+
},
551+
},
552+
} as unknown as SDKMessage);
553+
554+
// The advisor result lands on its own block index and names the tool it
555+
// closes, so completion cannot key off the stream index.
556+
harness.query.emit({
557+
type: "stream_event",
558+
session_id: "sdk-session-1",
559+
uuid: "stream-1",
560+
parent_tool_use_id: null,
561+
event: {
562+
type: "content_block_start",
563+
index: 1,
564+
content_block: {
565+
type: "advisor_tool_result",
566+
tool_use_id: "srvtoolu-advisor-1",
567+
content: {
568+
type: "advisor_redacted_result",
569+
encrypted_content: "opaque",
570+
},
571+
},
572+
},
573+
} as unknown as SDKMessage);
574+
575+
// No result message: the consult must close on its own result block. The
576+
// end-of-turn sweep that completes abandoned tool items never runs here,
577+
// so this fiber only joins if the advisor block did the work.
578+
const runtimeEvents = Array.from(yield* Fiber.join(runtimeEventsFiber));
579+
const advisorStarted = runtimeEvents.find((event) => event.type === "item.started");
580+
assert.equal(advisorStarted?.type, "item.started");
581+
if (advisorStarted?.type === "item.started") {
582+
assert.equal(String(advisorStarted.itemId), "srvtoolu-advisor-1");
583+
assert.equal(advisorStarted.payload.title, "Advisor consult");
584+
assert.equal(advisorStarted.payload.detail, undefined);
585+
}
586+
587+
const advisorCompletions = runtimeEvents.filter(
588+
(event) => event.type === "item.completed" && String(event.itemId) === "srvtoolu-advisor-1",
589+
);
590+
assert.equal(advisorCompletions.length, 1);
591+
const advisorCompleted = advisorCompletions[0];
592+
assert.equal(advisorCompleted?.type, "item.completed");
593+
if (advisorCompleted?.type === "item.completed") {
594+
assert.equal(advisorCompleted.payload.status, "completed");
595+
assert.equal(advisorCompleted.payload.title, "Advisor consult");
596+
}
597+
}).pipe(
598+
Effect.provideService(Random.Random, makeDeterministicRandomService()),
599+
Effect.provide(harness.layer),
600+
);
601+
});
602+
479603
it.effect("forwards claude effort levels into query options", () => {
480604
const harness = makeHarness();
481605
return Effect.gen(function* () {

‎apps/server/src/provider/Layers/ClaudeAdapter.ts‎

Lines changed: 85 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1228,6 +1228,24 @@ function summarizeToolRequest(toolName: string, input: Record<string, unknown>):
12281228
return `${toolName}: ${serialized.slice(0, 397)}...`;
12291229
}
12301230

1231+
/**
1232+
* The advisor is a server-side tool: Claude consults a second model mid-turn.
1233+
* It arrives as a `server_tool_use` block named `advisor` and its result comes
1234+
* back in the assistant stream, never as a `tool_result` user message.
1235+
*/
1236+
function isAdvisorToolName(toolName: string): boolean {
1237+
return toolName.toLowerCase() === "advisor";
1238+
}
1239+
1240+
/** The advisor result block, which closes the advisor tool item it names. */
1241+
function isAdvisorResultBlock(block: unknown): block is { readonly tool_use_id?: unknown } {
1242+
return (
1243+
typeof block === "object" &&
1244+
block !== null &&
1245+
(block as { readonly type?: unknown }).type === "advisor_tool_result"
1246+
);
1247+
}
1248+
12311249
function titleForTool(itemType: CanonicalItemType): string {
12321250
switch (itemType) {
12331251
case "command_execution":
@@ -2471,11 +2489,14 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
24712489
// Drop only the subagent's narration (text/thinking); tool_use blocks
24722490
// and their input_json_delta frames must flow so attributed tool items
24732491
// keep their inputs (review finding: dropping deltas emptied inputs).
2492+
// The advisor result block flows for the same reason: it is what closes
2493+
// the subagent's advisor tool item.
24742494
const dropStart =
24752495
event.type === "content_block_start" &&
24762496
event.content_block.type !== "tool_use" &&
24772497
event.content_block.type !== "server_tool_use" &&
2478-
event.content_block.type !== "mcp_tool_use";
2498+
event.content_block.type !== "mcp_tool_use" &&
2499+
!isAdvisorResultBlock(event.content_block);
24792500
const dropDelta =
24802501
event.type === "content_block_delta" &&
24812502
(event.delta.type === "text_delta" || event.delta.type === "thinking_delta");
@@ -2668,6 +2689,59 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
26682689
});
26692690
return;
26702691
}
2692+
// The advisor's result closes the tool block that started it. It never
2693+
// arrives as a `tool_result` user message, so without this the item
2694+
// spins until the turn's end-of-result sweep completes it.
2695+
if (isAdvisorResultBlock(block)) {
2696+
const advisorToolUseId =
2697+
typeof block.tool_use_id === "string" ? block.tool_use_id : undefined;
2698+
const advisorEntry = advisorToolUseId
2699+
? Array.from(context.inFlightTools.entries()).find(
2700+
([, inFlight]) => inFlight.itemId === advisorToolUseId,
2701+
)
2702+
: undefined;
2703+
if (!advisorEntry) {
2704+
return;
2705+
}
2706+
const [advisorIndex, advisorTool] = advisorEntry;
2707+
context.inFlightTools.delete(advisorIndex);
2708+
const advisorStamp = yield* makeEventStamp();
2709+
yield* offerRuntimeEvent({
2710+
type: "item.completed",
2711+
eventId: advisorStamp.eventId,
2712+
provider: PROVIDER,
2713+
createdAt: advisorStamp.createdAt,
2714+
threadId: context.session.threadId,
2715+
...(context.turnState ? { turnId: asCanonicalTurnId(context.turnState.turnId) } : {}),
2716+
itemId: asRuntimeItemId(advisorTool.itemId),
2717+
payload: {
2718+
itemType: advisorTool.itemType,
2719+
status: "completed",
2720+
title: advisorTool.title,
2721+
...(advisorTool.detail ? { detail: advisorTool.detail } : {}),
2722+
...(advisorTool.agentId ? { agentId: advisorTool.agentId } : {}),
2723+
...(advisorTool.parentToolUseId
2724+
? { parentToolUseId: advisorTool.parentToolUseId }
2725+
: {}),
2726+
// The advisor's advice is returned encrypted, so there is no result
2727+
// text to carry: the item records that the consult happened.
2728+
data: {
2729+
toolName: advisorTool.toolName,
2730+
input: advisorTool.input,
2731+
},
2732+
},
2733+
providerRefs: nativeProviderRefs(context, {
2734+
providerItemId: advisorTool.itemId,
2735+
}),
2736+
raw: {
2737+
source: "claude.sdk.message",
2738+
method: "claude/stream_event/content_block_start",
2739+
payload: message,
2740+
},
2741+
});
2742+
return;
2743+
}
2744+
26712745
if (
26722746
block.type !== "tool_use" &&
26732747
block.type !== "server_tool_use" &&
@@ -2683,7 +2757,10 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
26832757
: {};
26842758
const itemType = classifyToolItemType(toolName, toolInput);
26852759
const itemId = block.id;
2686-
const detail = summarizeToolRequest(toolName, toolInput);
2760+
// The advisor takes no arguments, so the generic input summary reads
2761+
// "advisor: {}". Its title carries the meaning instead.
2762+
const isAdvisor = isAdvisorToolName(toolName);
2763+
const detail = isAdvisor ? undefined : summarizeToolRequest(toolName, toolInput);
26872764
const inputFingerprint =
26882765
Object.keys(toolInput).length > 0 ? toolInputFingerprint(toolInput) : undefined;
26892766

@@ -2699,8 +2776,8 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
26992776
itemId,
27002777
itemType,
27012778
toolName,
2702-
title: titleForTool(itemType),
2703-
detail,
2779+
title: isAdvisor ? "Advisor consult" : titleForTool(itemType),
2780+
...(detail ? { detail } : {}),
27042781
input: toolInput,
27052782
partialInputJson: "",
27062783
...(inputFingerprint ? { lastEmittedInputFingerprint: inputFingerprint } : {}),
@@ -4357,6 +4434,10 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
43574434
...(claudeSettings.autoCompactWindow
43584435
? { autoCompactWindow: Number(claudeSettings.autoCompactWindow) }
43594436
: {}),
4437+
// Settings key, not the `--advisor` flag: the flag aborts session start
4438+
// when the advisor cannot advise the thread model, while this path logs
4439+
// and runs the turn without an advisor.
4440+
...(claudeSettings.advisorModel ? { advisorModel: claudeSettings.advisorModel } : {}),
43604441
};
43614442
const mcpSession = McpProviderSession.readMcpProviderSession(input.threadId);
43624443
// The attachments dir grant lets the agent Read/copy pasted images at

‎apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,7 @@ const makeClaudeConfig = (overrides: Partial<ClaudeSettings>): ClaudeSettings =>
111111
customModels: [],
112112
launchArgs: "",
113113
autoCompactWindow: "",
114+
advisorModel: "",
114115
...overrides,
115116
});
116117

‎apps/server/src/serverSettings.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,7 @@ it.layer(NodeServices.layer)("server settings", (it) => {
234234
customModels: ["claude-custom"],
235235
launchArgs: "",
236236
autoCompactWindow: "",
237+
advisorModel: "",
237238
});
238239
assert.deepEqual(
239240
next.textGenerationModelSelection,
@@ -899,6 +900,7 @@ it.layer(NodeServices.layer)("server settings", (it) => {
899900
customModels: [],
900901
launchArgs: "",
901902
autoCompactWindow: "",
903+
advisorModel: "",
902904
});
903905
assert.deepEqual(next.providers.opencode, {
904906
// OpenCode is disabled by default; this update only touches paths.

‎apps/web/src/components/settings/ProviderSettingsForm.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ describe("ProviderSettingsForm helpers", () => {
6767
expect(deriveProviderSettingsFields(claude!).map((field) => field.key)).toEqual([
6868
"binaryPath",
6969
"homePath",
70+
"advisorModel",
7071
"autoCompactWindow",
7172
"launchArgs",
7273
]);

‎docs/user/providers-claude.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,26 @@ offers to compact the conversation before you continue. You can also select **Co
4646
from the context meter. On every client, you can enter `/compact` in the message composer, and
4747
Claude can show its own resume prompt when you continue an old session.
4848

49+
## Let Claude Ask A Second Model For Advice
50+
51+
Claude can consult a stronger model during a turn. The second model sees the work so far and gives
52+
guidance before Claude continues.
53+
54+
In Settings, open your Claude provider and set **Advisor model** to `fable`, `opus`, or `sonnet`.
55+
Leave the field empty to keep the advisor setting from your Claude Code configuration.
56+
57+
The advisor must be at least as capable as the model of the thread. For example, `sonnet` cannot
58+
advise an Opus thread. If the two models do not match, Claude Code runs the turn without an
59+
advisor.
60+
61+
`fable` bills to usage credits. You must set up usage credits for your account before the advisor
62+
can use `fable`. Run `/model fable` in an interactive Claude Code session to review and enable it.
63+
Until you do this, T3 Code runs the turn without an advisor and shows no message.
64+
65+
Each consult shows in the timeline as **Advisor consult**. The advice itself is encrypted, so the
66+
item shows that the consult happened and no text. The advisor model uses its own tokens, which are
67+
additional to the tokens of the thread model.
68+
4969
## Where Claude Skills Are Loaded
5070

5171
T3 Code looks for Claude skills in the Claude config directory's `skills` folder and

‎packages/contracts/src/settings.test.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,22 @@ describe("ClaudeSettings auto-compaction", () => {
5050
});
5151
});
5252

53+
describe("ClaudeSettings advisor model", () => {
54+
it("inherits Claude's own advisor setting when none is configured", () => {
55+
expect(decodeClaudeSettings({}).advisorModel).toBe("");
56+
});
57+
58+
it("keeps a configured advisor alias", () => {
59+
expect(decodeClaudeSettings({ advisorModel: "opus" }).advisorModel).toBe("opus");
60+
});
61+
62+
it("accepts an advisor model at the settings patch boundary", () => {
63+
expect(
64+
decodeServerSettingsPatch({ providers: { claudeAgent: { advisorModel: "fable" } } }),
65+
).toBeDefined();
66+
});
67+
});
68+
5369
describe("ClientSettings word wrap", () => {
5470
it("defaults word wrap on", () => {
5571
expect(decodeClientSettings({}).wordWrap).toBe(true);

‎packages/contracts/src/settings.ts‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -528,9 +528,21 @@ export const ClaudeSettings = makeProviderSettingsSchema(
528528
},
529529
}),
530530
),
531+
advisorModel: TrimmedString.pipe(
532+
Schema.withDecodingDefault(Effect.succeed("")),
533+
Schema.annotateKey({
534+
title: "Advisor model",
535+
description:
536+
"Let Claude consult a second model during a turn. Use fable, opus, or sonnet. The advisor must be at least as capable as the thread model. Leave empty to use Claude's own setting.",
537+
providerSettingsForm: {
538+
placeholder: "e.g. opus",
539+
clearWhenEmpty: "omit",
540+
},
541+
}),
542+
),
531543
},
532544
{
533-
order: ["binaryPath", "homePath", "autoCompactWindow", "launchArgs"],
545+
order: ["binaryPath", "homePath", "advisorModel", "autoCompactWindow", "launchArgs"],
534546
},
535547
);
536548
export type ClaudeSettings = typeof ClaudeSettings.Type;
@@ -1050,6 +1062,7 @@ const ClaudeSettingsPatch = Schema.Struct({
10501062
autoCompactWindow: Schema.optionalKey(
10511063
TrimmedString.check(Schema.isPattern(CLAUDE_AUTO_COMPACT_WINDOW_PATTERN)),
10521064
),
1065+
advisorModel: Schema.optionalKey(TrimmedString),
10531066
});
10541067

10551068
const CursorSettingsPatch = Schema.Struct({

0 commit comments

Comments
 (0)