The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 12:15 UTC
docs: align delegation guide with current MCP contract (#31045)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
jacobcorbett committed
Nov 15, 2026 at 04:55 UTC
12042ffb29349c8da2382bd8d92836f9bcae0fe8
1 file changed
+25
-69
docs/orchestration-v2/orchestrator-mcp-server.md
+25
-69
@@ -232,31 +232,31 @@ any catalog model.
232
Creates a T3-owned child thread and immediately dispatches the supplied task
233
prompt.
234
235
+The [shared contract](../../packages/contracts/src/orchestratorMcp.ts) is authoritative for
236
+inputs and results, including target options and linked-environment fields.
237
+
238
```ts
236
-type DelegateTaskInput = {
237
- task: string;
238
- target?: {
239
- providerInstanceId?: string;
240
- driverKind?: string;
241
- model?: string;
242
- };
243
- title?: string;
244
- role?: "implementation" | "research" | "review" | "design" | "test" | "general";
245
- mode?: "async" | "wait";
246
- timeoutMs?: number;
247
- clientRequestId?: string;
248
- runtimeMode?: "inherit" | "approval-required" | "auto-accept-edits" | "full-access";
249
- interactionMode?: "inherit" | "plan" | "default";
250
-};
239
+import type {
240
+ OrchestratorMcpDelegateTaskInput as DelegateTaskInput,
241
+ OrchestratorMcpDelegateTaskResult as DelegateTaskResult,
242
+} from "@t3tools/contracts";
243
```
244
253
-Provider, model, runtime mode, and interaction mode inherit from the parent
254
-when omitted. A driver-only target inherits the parent's provider instance
245
+For local delegation, provider, model, runtime mode, and interaction mode inherit
246
+from the parent when omitted. A driver-only target inherits the parent's provider instance
247
when it can run child tasks, and otherwise selects an available instance of
248
that driver; an explicit `providerInstanceId` is honored exactly and fails
249
when unavailable. Selecting a different provider without a model uses that
250
provider's first advertised model.
251
252
+Set `target.options` using the options returned by `orchestrator_capabilities`, such as
253
+`{effort: "max"}`. Supplied values override inherited selections; `{}` or `[]` clears them.
254
+For local delegation, use `isolation: "worktree"` for a separate prepared checkout from
255
+the parent's commit; the default `"shared"` uses the parent's checkout. Uncommitted parent
256
+edits are not copied. A linked-environment target (`target.environmentId`) runs in the remote
257
+project's checkout and rejects worktree isolation. To launch an isolated thread there, use
258
+`t3_thread_launch` with `environmentId` and a worktree `workspaceStrategy`.
259
+
260
A provider runs a runtime mode it does not offer as `approval-required`, so a
261
child would ask for approval on every command. `orchestrator_capabilities`
262
lists `runtimeModes` only for a provider that offers some of the modes, and
@@ -280,8 +280,10 @@ provider session. The request becomes the V2 command
280
`mode: "async"` returns the current durable state immediately.
281
`mode: "wait"` waits for the task result, including nested work and completion follow-ups, or until
282
the timeout expires. A wait timeout does not cancel the child; the result sets
283
-`waitTimedOut: true`, and the caller can continue with `task_status`. A pending blocking
284
-question also ends the wait with `hasPendingQuestion: true` and `waitTimedOut: false`.
283
+`waitTimedOut: true`. When the result includes `next`, completion wakes the parent:
284
+do not wait on the task or poll it; continue other work, and end the turn when none is
285
+left. A pending blocking question also ends the wait with `hasPendingQuestion: true` and
286
+`waitTimedOut: false`.
287
If `hasPendingQuestion`, pass `threadId=childThreadId` to `t3_pending_request` with
288
action `list`, `read` (with `requestId`), or `respond`, or ask the user; the task's completion still wakes this thread. A pending live approval for the
289
task's own unfinished work also ends the wait. Its identity appears in `pendingApproval`;
@@ -289,41 +291,6 @@ it grants no approval authority. Read the fresh full request in the child thread
291
responding, since the durable record can outlive its provider callback. Async questions
292
do not end the wait.
293
292
-```ts
293
-type DelegateTaskResult = {
294
- taskId: string;
295
- childThreadId: string;
296
- childRunId: string | null;
297
- childNodeId: string;
298
- status:
299
- | "queued"
300
- | "starting"
301
- | "running"
302
- | "waiting"
303
- | "completed"
304
- | "failed"
305
- | "cancelled"
306
- | "interrupted";
307
- workState: "working" | "waiting_for_children" | "result_available";
308
- hasPendingChildRuns: boolean;
309
- providerInstanceId: string;
310
- model: string | null;
311
- summary: string | null;
312
- resultContextTransferId: string | null;
313
- latestTerminalRunId: string | null;
314
- latestTerminalStatus: "completed" | "failed" | "cancelled" | "interrupted" | null;
315
- latestTerminalSummary: string | null;
316
- latestTerminalResultContextTransferId: string | null;
317
- hasPendingQuestion: boolean;
318
- pendingApproval: {
319
- requestId: string;
320
- kind: "command" | "file-read" | "file-change" | "mcp-elicitation" | "permission";
321
- runId: string;
322
- } | null;
323
- waitTimedOut: boolean;
324
-};
325
-```
326
-
294
### `task_status`
295
296
Reads a delegated task from the parent thread's durable projection. A task ID
@@ -360,26 +327,15 @@ optional cancellation reason.
327
Creates between one and twenty ordinary top-level T3 threads:
328
329
```ts
363
-type CreateThreadsInput = {
364
- threads: Array<{
365
- prompt?: string;
366
- title?: string;
367
- target?: {
368
- providerInstanceId?: string;
369
- driverKind?: string;
370
- model?: string;
371
- };
372
- runtimeMode?: "inherit" | "approval-required" | "auto-accept-edits" | "full-access";
373
- interactionMode?: "inherit" | "plan" | "default";
374
- }>;
375
- clientRequestId?: string;
376
-};
330
+import type { OrchestratorMcpCreateThreadsInput as CreateThreadsInput } from "@t3tools/contracts";
331
```
332
333
Each entry independently resolves provider, model, and modes. The new threads
334
inherit the parent's project, branch, and worktree path, but they have no
335
sub-agent lineage. Entries with a prompt immediately dispatch a run; entries
382
-without a prompt remain idle.
336
+without a prompt remain idle. `create_threads` is local-only: `target.environmentId` and
337
+`target.projectId` are ignored even though the shared target contract accepts them. Use
338
+`t3_thread_launch` with `environmentId` and `projectId` to select another environment or project.
339
340
### `t3_thread_launch`
341