@devries-cameron20 / t3code Mirror · read-only / commits / 12042ffb29
Fork 0

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