@devries-cameron20 / t3code-1 / commits / 003b64dfa5
Fork 0

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)");