Skip to content

Commit d2c2595

Browse files
fix(server): tell outside agents which MCP tools need a thread and that t3_thread_list takes allProjects (#26525)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 896e64f commit d2c2595

3 files changed

Lines changed: 32 additions & 7 deletions

File tree

‎apps/server/src/mcp/OrchestratorMcpService.test.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3622,6 +3622,15 @@ describe("OrchestratorMcpService thread list", () => {
36223622
);
36233623
}).pipe(Effect.provide(service)),
36243624
);
3625+
3626+
it.effect("points a caller outside any thread at allProjects when it omits projectId", () =>
3627+
Effect.gen(function* () {
3628+
const mcp = yield* OrchestratorMcpService.OrchestratorMcpService;
3629+
const error = yield* mcp.listThreads(client, {}).pipe(Effect.flip);
3630+
assert.equal(error.code, "target_required");
3631+
assert.include(error.message, "allProjects");
3632+
}).pipe(Effect.provide(service)),
3633+
);
36253634
});
36263635

36273636
describe("OrchestratorMcpService thread stop", () => {

‎apps/server/src/mcp/OrchestratorMcpService.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1142,17 +1142,13 @@ const make = Effect.gen(function* () {
11421142
const resolveProjectTarget = (
11431143
parent: Pick<OrchestrationV2ThreadProjection, "thread"> | undefined,
11441144
projectId: ProjectId | undefined,
1145+
missingMessage = "Pass projectId: this MCP client is not running inside a T3 thread.",
11451146
) =>
11461147
projectId !== undefined
11471148
? Effect.succeed(projectId)
11481149
: parent !== undefined
11491150
? Effect.succeed(parent.thread.projectId)
1150-
: Effect.fail(
1151-
failure(
1152-
"target_required",
1153-
"Pass projectId: this MCP client is not running inside a T3 thread.",
1154-
),
1155-
);
1151+
: Effect.fail(failure("target_required", missingMessage));
11561152

11571153
const loadTargetThread = Effect.fn("OrchestratorMcpService.loadTargetThread")(function* (
11581154
threadId: ThreadId,
@@ -2964,7 +2960,11 @@ const make = Effect.gen(function* () {
29642960
const { parent } = yield* loadCaller(scope, []);
29652961
const projectId = input.allProjects
29662962
? null
2967-
: yield* resolveProjectTarget(parent, input.projectId);
2963+
: yield* resolveProjectTarget(
2964+
parent,
2965+
input.projectId,
2966+
"Pass projectId, or allProjects: true for every project. This MCP client is not running inside a T3 thread.",
2967+
);
29682968
const projectThreads = yield* threadManagement
29692969
.listProjectThreads({
29702970
projectId: projectId ?? undefined,

‎docs/user/outside-agents.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,22 @@ policy. Approving without a code starts at **Read only**:
8080
threads in every project. A thread it starts or steers cannot run with more
8181
permissions than the mode you chose.
8282

83+
## What outside agents can call
84+
85+
Some tools only work for an agent running inside a T3 thread, because they act
86+
as that thread: subagents, secret requests, rendered HTML, the browser preview,
87+
devices, and worktree handoff. They still appear in an outside agent's tool
88+
list, but calling one returns an error saying it needs an agent running inside
89+
T3 Code.
90+
91+
- To hand off work, start a thread with `t3_thread_launch`, then follow it with
92+
`t3_thread_wait` or `t3_thread_read`, instead of `create_threads` or
93+
`delegate_task`.
94+
- Tools that default to the caller's own project or thread need an explicit
95+
`projectId` or `threadId`.
96+
- To list threads across projects, call `t3_thread_list` with
97+
`allProjects: true`, or use `t3_thread_search`.
98+
8399
## Claude Code
84100

85101
```sh

0 commit comments

Comments
 (0)