The best way to control Claude Code, Codex and more from any computer or phone
feat(server): thread tools return a ready t3-thread link (#24784)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Oct 25, 2026 at 01:04 UTC
003b64dfa536e545079565d36ae0c2a5dba73b34
11 files changed
+47
-14
apps/server/src/mcp/OrchestratorMcpService.test.ts
+9
-9
@@ -89,7 +89,7 @@ describe("OrchestratorMcpService", () => {
89
],
90
} as unknown as OrchestrationV2ThreadProjection;
91
const childProjection = {
92
- thread: { id: childThreadId },
92
+ thread: { id: childThreadId, title: "Child" },
93
runs: [
94
{
95
id: childRunId,
@@ -223,7 +223,7 @@ describe("OrchestratorMcpService", () => {
223
],
224
} as unknown as OrchestrationV2ThreadProjection;
225
const childProjection = {
226
- thread: { id: childThreadId },
226
+ thread: { id: childThreadId, title: "Child" },
227
runs: [
228
{
229
id: RunId.make("run:mcp-restart-child"),
@@ -316,7 +316,7 @@ describe("OrchestratorMcpService", () => {
316
],
317
} as unknown as OrchestrationV2ThreadProjection;
318
const childProjection = {
319
- thread: { id: childThreadId },
319
+ thread: { id: childThreadId, title: "Child" },
320
runs: [],
321
contextTransfers: [],
322
messages: [],
@@ -400,7 +400,7 @@ describe("OrchestratorMcpService", () => {
400
}) as unknown as OrchestrationV2ThreadProjection;
401
// A finished run whose binding to the follow-up was lost.
402
const childProjection = {
403
- thread: { id: childThreadId },
403
+ thread: { id: childThreadId, title: "Child" },
404
runs:
405
childState === "no runs"
406
? []
@@ -503,7 +503,7 @@ describe("OrchestratorMcpService", () => {
503
],
504
} as unknown as OrchestrationV2ThreadProjection;
505
const childProjection = {
506
- thread: { id: childThreadId },
506
+ thread: { id: childThreadId, title: "Child" },
507
runs: [{ id: childRunId, status: "running" }],
508
contextTransfers: [],
509
messages: [],
@@ -583,7 +583,7 @@ describe("OrchestratorMcpService", () => {
583
],
584
} as unknown as OrchestrationV2ThreadProjection;
585
const childProjection = {
586
- thread: { id: childThreadId },
586
+ thread: { id: childThreadId, title: "Child" },
587
runs: [{ id: childRunId, status: "running" }],
588
contextTransfers: [],
589
messages: [],
@@ -669,7 +669,7 @@ describe("OrchestratorMcpService", () => {
669
],
670
} as unknown as OrchestrationV2ThreadProjection;
671
const childProjection = {
672
- thread: { id: childThreadId },
672
+ thread: { id: childThreadId, title: "Child" },
673
runs: [{ id: childRunId, status: "running" }],
674
contextTransfers: [],
675
messages: [],
@@ -764,7 +764,7 @@ describe("OrchestratorMcpService", () => {
764
[
765
childThreadId,
766
{
767
- thread: { id: childThreadId },
767
+ thread: { id: childThreadId, title: "Child" },
768
runs: [{ id: RunId.make("run:mcp-cancel-grandchild-child"), status: "running" }],
769
contextTransfers: [],
770
messages: [],
@@ -992,7 +992,7 @@ describe("OrchestratorMcpService provider resolution", () => {
992
}) as unknown as OrchestrationV2ThreadProjection;
993
994
const childProjection = {
995
- thread: { id: childThreadId },
995
+ thread: { id: childThreadId, title: "Child" },
996
runs: [],
997
contextTransfers: [],
998
messages: [],
apps/server/src/mcp/OrchestratorMcpService.ts
+6
@@ -67,6 +67,7 @@ import {
67
} from "@t3tools/contracts";
68
import { getProviderOptionCurrentValue } from "@t3tools/shared/model";
69
import { runRanAfter } from "@t3tools/shared/orchestrationV2ThreadError";
70
+import { formatThreadLink } from "@t3tools/shared/threadLinks";
71
import {
72
normalizeThreadPullRequestKey,
73
visibleThreadPullRequests,
@@ -855,6 +856,7 @@ function listItemFromShell(
856
return {
857
threadId: shell.id,
858
title: shell.title,
859
+ link: formatThreadLink(shell.id, shell.title),
860
createdBy: shell.createdBy,
861
creationSource: shell.creationSource,
862
status: shell.activityRunStatus ?? shell.status,
@@ -887,6 +889,7 @@ function threadDetail(
889
threadId: projection.thread.id,
890
projectId: projection.thread.projectId,
891
title: projection.thread.title,
892
+ link: formatThreadLink(projection.thread.id, projection.thread.title),
893
createdBy: projection.thread.createdBy,
894
creationSource: projection.thread.creationSource,
895
status: active?.status ?? latest?.status ?? "idle",
@@ -1597,6 +1600,7 @@ const make = Effect.gen(function* () {
1600
const response = {
1601
taskId: task.id,
1602
childThreadId: task.childThreadId,
1603
+ link: formatThreadLink(task.childThreadId, childControls.thread.title),
1604
childRunId: childRun?.id ?? null,
1605
childNodeId: task.id,
1606
status,
@@ -2648,6 +2652,7 @@ const make = Effect.gen(function* () {
2652
);
2653
return {
2654
threadId,
2655
+ link: formatThreadLink(threadId, projection.thread.title),
2656
runId: run?.id ?? null,
2657
status: run?.status ?? "idle",
2658
title: projection.thread.title,
@@ -2839,6 +2844,7 @@ const make = Effect.gen(function* () {
2844
);
2845
return {
2846
threadId: input.threadId,
2847
+ link: formatThreadLink(input.threadId, target.thread.title),
2848
messageId,
2849
runId: result.run.id,
2850
...(result.run.delegatedTaskId === undefined ? {} : { taskId: result.run.delegatedTaskId }),
apps/server/src/mcp/toolkits/orchestrator/tools.ts
+2
-2
@@ -214,7 +214,7 @@ const CreateThreadsTool = Tool.make("create_threads", {
214
215
const ThreadListTool = Tool.make("t3_thread_list", {
216
description:
217
- "List T3 threads in a project, newest first. Omit projectId for the calling thread's project. Filter by durable run status, title, or settled state (settled=true lists threads the user or auto-settlement moved out of the active list), or snoozed state, and paginate with the returned cursor. A snoozed thread wakes early only when it asks for something or fails after snoozing; completed runs and background wakes keep it snoozed. pullRequests lists every pull request linked to each thread; linkedPullRequest is a legacy single link and can be null while pullRequests still has entries. To link a thread for the user, write `[title](t3-thread://v1/<threadId>)` with the threadId exactly as returned, not URL-encoded; T3 Code shows the thread's current title.",
217
+ "List T3 threads in a project, newest first. Omit projectId for the calling thread's project. Filter by durable run status, title, or settled state (settled=true lists threads the user or auto-settlement moved out of the active list), or snoozed state, and paginate with the returned cursor. A snoozed thread wakes early only when it asks for something or fails after snoozing; completed runs and background wakes keep it snoozed. pullRequests lists every pull request linked to each thread; linkedPullRequest is a legacy single link and can be null while pullRequests still has entries. Mention a thread with its `link`.",
218
parameters: OrchestratorMcpThreadListInput,
219
success: OrchestratorMcpThreadListResult,
220
failure: OrchestratorMcpFailure,
@@ -228,7 +228,7 @@ const ThreadListTool = Tool.make("t3_thread_list", {
228
229
const ThreadReadTool = Tool.make("t3_thread_read", {
230
description:
231
- "Read durable state and a paginated timeline from any T3 thread in this environment. The default messages view returns user messages, assistant messages, and proposed plans; activity returns all summarized timeline items. Reading an untruncated terminal assistant result from this parent thread's direct app-owned child acknowledges that child's automatic completion delivery. Continue with afterPosition=nextPosition. Recover long item text with itemId and textOffset=nextTextOffset until nextTextOffset is null; offsets count UTF-16 code units. The thread also reports its snooze state and, in pullRequests, every linked pull request; linkedPullRequest is a legacy single link and can be null while pullRequests still has entries. To link a thread for the user, write `[title](t3-thread://v1/<threadId>)` with the threadId exactly as returned, not URL-encoded; T3 Code shows the thread's current title.",
231
+ "Read durable state and a paginated timeline from any T3 thread in this environment. The default messages view returns user messages, assistant messages, and proposed plans; activity returns all summarized timeline items. Reading an untruncated terminal assistant result from this parent thread's direct app-owned child acknowledges that child's automatic completion delivery. Continue with afterPosition=nextPosition. Recover long item text with itemId and textOffset=nextTextOffset until nextTextOffset is null; offsets count UTF-16 code units. The thread also reports its snooze state and, in pullRequests, every linked pull request; linkedPullRequest is a legacy single link and can be null while pullRequests still has entries. Mention a thread with its `link`.",
232
parameters: OrchestratorMcpThreadReadInput,
233
success: OrchestratorMcpThreadReadResult,
234
failure: OrchestratorMcpFailure,
apps/server/src/mcp/toolkits/project/handlers.test.ts
+2
@@ -81,6 +81,7 @@ const clientLaunchHarness = (input: {
81
thread: {
82
id: launch.threadId,
83
projectId: launch.projectId,
84
+ title: launch.title,
85
modelSelection: launch.modelSelection,
86
},
87
runs: [],
@@ -159,6 +160,7 @@ it.effect(
160
expect(belowCeiling.result).toMatchObject({
161
projectId: belowCeiling.projectId,
162
modelSelection: belowCeiling.modelSelection,
163
+ link: `[Fix](t3-thread://v1/${belowCeiling.launched[0]?.threadId})`,
164
});
165
expect(belowCeiling.launched[0]?.runtimeMode).toBe("approval-required");
166
expect(belowCeiling.launched[0]?.initialMessage?.senderThreadId).toBeUndefined();
apps/server/src/mcp/toolkits/project/handlers.ts
+2
@@ -11,6 +11,7 @@ import * as Repositories from "../../../sourceControl/SourceControlRepositorySer
11
import * as GitVcsDriver from "../../../vcs/GitVcsDriver.ts";
12
import * as ServerSettings from "../../../serverSettings.ts";
13
import { resolveProjectSettings } from "@t3tools/shared/projectSettings";
14
+import { formatThreadLink } from "@t3tools/shared/threadLinks";
15
import { resolveRuntimeMode } from "../../OrchestratorMcpService.ts";
16
import * as McpToolAccess from "../../McpToolAccess.ts";
17
import { newCommandId, readCaller, resolveProjectId, unavailable } from "../../threadAccess.ts";
@@ -197,6 +198,7 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, {
198
const run = result.projection.runs.find((run) => run.userMessageId === messageId);
199
return {
200
threadId: thread.id,
201
+ link: formatThreadLink(thread.id, thread.title),
202
projectId: thread.projectId,
203
modelSelection: thread.modelSelection,
204
runId: run?.id ?? null,
apps/server/src/mcp/toolkits/project/tools.ts
+2
-1
@@ -104,7 +104,7 @@ const ProjectCloneTool = Tool.make("t3_project_clone", {
104
const ThreadLaunchTool = Tool.make("t3_thread_launch", {
105
...shared,
106
description:
107
- 'Create an ordinary TOP-LEVEL thread with an explicit workspace binding before its agent starts. Use this when the user requests independent work, a new thread, or a PR stack in its own worktree; use delegate_task for child subagents. Set workspaceStrategy to {type:"worktree",baseRef:"parent-branch",branch:"new-branch",startFromOrigin:false} for a new worktree based on local commits, or {type:"existing_worktree",worktreePath:"/absolute/path",branch:"existing-branch"} to use an existing checkout. To fetch and start from the base branch\'s remote, set startFromOrigin:true. Omitted workspaceStrategy means the project root, NOT the caller\'s worktree. Omit projectId/modelSelection/modes to inherit those settings from the calling thread; a caller outside a T3 thread must pass projectId and gets the project\'s default model. Set scratch:true instead of projectId for a thread without a project: it runs in a fresh folder of its own, outside any repository. Put the task in message. Do not ask the agent to create its own worktree via shell: that does not update the thread binding. Each call creates a new launch with no retry key; retain threadId and use t3_thread_read/t3_thread_wait to follow preparation. To link a thread for the user, write `[title](t3-thread://v1/<threadId>)` with the threadId exactly as returned, not URL-encoded; T3 Code shows the thread\'s current title. After errors or lost responses, inspect t3_thread_list before retrying. Attachments must be pending uploads. The new thread may not run with broader runtime or interaction modes than the caller: the calling T3 thread\'s own modes, or the permission mode an outside agent was approved with.',
107
+ 'Create an ordinary TOP-LEVEL thread with an explicit workspace binding before its agent starts. Use this when the user requests independent work, a new thread, or a PR stack in its own worktree; use delegate_task for child subagents. Set workspaceStrategy to {type:"worktree",baseRef:"parent-branch",branch:"new-branch",startFromOrigin:false} for a new worktree based on local commits, or {type:"existing_worktree",worktreePath:"/absolute/path",branch:"existing-branch"} to use an existing checkout. To fetch and start from the base branch\'s remote, set startFromOrigin:true. Omitted workspaceStrategy means the project root, NOT the caller\'s worktree. Omit projectId/modelSelection/modes to inherit those settings from the calling thread; a caller outside a T3 thread must pass projectId and gets the project\'s default model. Set scratch:true instead of projectId for a thread without a project: it runs in a fresh folder of its own, outside any repository. Put the task in message. Do not ask the agent to create its own worktree via shell: that does not update the thread binding. Each call creates a new launch with no retry key; retain threadId and use t3_thread_read/t3_thread_wait to follow preparation. Mention a thread with its `link`. After errors or lost responses, inspect t3_thread_list before retrying. Attachments must be pending uploads. The new thread may not run with broader runtime or interaction modes than the caller: the calling T3 thread\'s own modes, or the permission mode an outside agent was approved with.',
108
parameters: Schema.Struct({
109
projectId: Schema.optional(ProjectId),
110
scratch: Schema.optional(
@@ -133,6 +133,7 @@ const ThreadLaunchTool = Tool.make("t3_thread_launch", {
133
}),
134
success: Schema.Struct({
135
threadId: ThreadId,
136
+ link: Schema.optional(Schema.String),
137
projectId: ProjectId,
138
modelSelection: ModelSelection,
139
runId: Schema.NullOr(RunId),
apps/server/src/mcp/toolkits/thread/handlers.ts
+8
-1
@@ -9,6 +9,7 @@ import {
9
} from "@t3tools/contracts";
10
import * as Effect from "effect/Effect";
11
import { modelSelectionCommandType } from "@t3tools/shared/model";
12
+import { formatThreadLink } from "@t3tools/shared/threadLinks";
13
14
import * as McpToolAccess from "../../McpToolAccess.ts";
15
import {
@@ -105,9 +106,15 @@ export const layer = McpToolAccess.toLayer(ThreadToolkit, {
106
Effect.gen(function* () {
107
const { caller } = yield* readCaller();
108
const threadSearch = yield* ThreadSearch.ThreadSearch;
108
- return yield* threadSearch
109
+ const { matches } = yield* threadSearch
110
.searchThreads({ ...input, projectId: input.projectId ?? caller?.projectId })
111
.pipe(Effect.mapError(unavailable));
112
+ return {
113
+ matches: matches.map((match) => ({
114
+ ...match,
115
+ link: formatThreadLink(match.threadId, match.title),
116
+ })),
117
+ };
118
}),
119
),
120
t3_thread_fork: writesThread((input) =>
apps/server/src/mcp/toolkits/thread/tools.ts
+1
@@ -254,6 +254,7 @@ const ThreadSearchTool = Tool.make("t3_thread_search", {
254
threadId: OrchestrationThreadSearchMatch.fields.threadId,
255
projectId: OrchestrationThreadSearchMatch.fields.projectId,
256
title: Schema.String,
257
+ link: Schema.optional(Schema.String),
258
source: Schema.Literals(["title", "user", "assistant"]),
259
snippet: Schema.optional(OrchestrationThreadSearchMatch.fields.snippet),
260
messageCreatedAt: Schema.optional(OrchestrationThreadSearchMatch.fields.messageCreatedAt),
docs/orchestration-v2/orchestrator-mcp-server.md
+2
-1
@@ -391,7 +391,8 @@ and `creationSource: "mcp"`; provider output uses `creationSource: "provider"`.
391
Actor and ingress are separate so agent-authored user-role messages remain
392
distinguishable from human-authored messages.
393
394
-Agents mention another thread as `[title](t3-thread://v1/<threadId>)`. The
394
+Agents mention another thread as `[title](t3-thread://v1/<threadId>)`. Thread
395
+results carry this ready-made as `link`, so agents never format the id. The
396
link carries only the id. Clients first resolve it in the message's environment,
397
then use a unique match in another enabled environment. Ambiguous matches stay
398
unresolved. Web and desktop show the resolved thread’s current title. Mobile
packages/contracts/src/orchestratorMcp.ts
+5
@@ -190,6 +190,7 @@ export type OrchestratorMcpDelegateTaskInput = typeof OrchestratorMcpDelegateTas
190
export const OrchestratorMcpDelegateTaskResult = Schema.Struct({
191
taskId: NodeId,
192
childThreadId: ThreadId,
193
+ link: Schema.optional(Schema.String),
194
childRunId: Schema.NullOr(RunId),
195
childNodeId: NodeId,
196
status: OrchestratorMcpDelegatedTaskStatus,
@@ -273,6 +274,7 @@ export type OrchestratorMcpCreatedThreadStatus = typeof OrchestratorMcpCreatedTh
274
275
export const OrchestratorMcpCreatedThread = Schema.Struct({
276
threadId: ThreadId,
277
+ link: Schema.optional(Schema.String),
278
runId: Schema.NullOr(RunId),
279
status: OrchestratorMcpCreatedThreadStatus,
280
title: Schema.String,
@@ -327,6 +329,7 @@ export type OrchestratorMcpThreadPullRequest = typeof OrchestratorMcpThreadPullR
329
export const OrchestratorMcpThreadListItem = Schema.Struct({
330
threadId: ThreadId,
331
title: Schema.String,
332
+ link: Schema.optional(Schema.String),
333
createdBy: OrchestrationV2Actor,
334
creationSource: OrchestrationV2CreationSource,
335
status: OrchestratorMcpThreadStatus,
@@ -394,6 +397,7 @@ export const OrchestratorMcpThreadDetail = Schema.Struct({
397
threadId: ThreadId,
398
projectId: ProjectId,
399
title: Schema.String,
400
+ link: Schema.optional(Schema.String),
401
createdBy: OrchestrationV2Actor,
402
creationSource: OrchestrationV2CreationSource,
403
status: OrchestratorMcpThreadStatus,
@@ -475,6 +479,7 @@ export type OrchestratorMcpThreadSendInput = typeof OrchestratorMcpThreadSendInp
479
480
export const OrchestratorMcpThreadSendResult = Schema.Struct({
481
threadId: ThreadId,
482
+ link: Schema.optional(Schema.String),
483
messageId: MessageId,
484
runId: RunId,
485
taskId: Schema.optional(NodeId),
packages/shared/src/threadLinks.test.ts
+8
@@ -98,6 +98,14 @@ describe("thread links", () => {
98
);
99
});
100
101
+ it("writes the thread id verbatim so the link opens that exact thread", () => {
102
+ const link = formatThreadLink("thread:delegated-task:mcp%3A1", "Fix");
103
+ expect(link).toBe("[Fix](t3-thread://v1/thread:delegated-task:mcp%3A1)");
104
+ expect(parseThreadLinkHref(link.slice(link.indexOf("](") + 2, -1))).toBe(
105
+ "thread:delegated-task:mcp%3A1",
106
+ );
107
+ });
108
+
109
it("formats a label that would otherwise break the Markdown link", () => {
110
expect(formatThreadLink("t1", "Fix [ci] \\ build")).toBe("[Fix ci build](t3-thread://v1/t1)");
111
expect(formatThreadLink("t1", " ] ")).toBe("[t1](t3-thread://v1/t1)");