@devries-cameron20 / t3code Mirror · read-only
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, 03:37 UTC

main
md 634 lines 31 KB
Rendered Raw
1 # Orchestrator MCP Server
2
3 ## Purpose
4
5 T3 exposes V2 orchestration through its app-owned MCP endpoint. A provider
6 agent can use this endpoint to:
7
8 - create an app-owned sub-agent on any supported provider instance;
9 - wait for or poll the sub-agent's durable result;
10 - cancel an active delegated task; and
11 - create one or more ordinary top-level T3 threads;
12 - list a project's threads and incrementally read any thread;
13 - rename threads, regenerate titles, and link or unlink pull requests;
14 - send or steer follow-up messages;
15 - wait for or interrupt ordinary thread runs; and
16 - schedule recurring work that runs without an active turn.
17
18 These are T3 orchestration operations, not provider-native sub-agent APIs.
19 Delegated tasks always create a T3 child thread and run. The child receives
20 only the supplied task prompt, plus an optional role instruction supplied in
21 the same tool call. Parent conversation history is not copied into the child.
22
23 `ThreadManagementService` is the shared server application boundary for V2
24 WebSocket commands and MCP. It owns thread lookup, listing, send-mode
25 selection, durable send postconditions, wait polling, and interrupt selection;
26 `OrchestratorV2` remains the lower-level command/event processor. Transport
27 adapters only authenticate, resolve transport-specific inputs, and shape
28 responses.
29
30 ## Transport And Authentication
31
32 The orchestration tools share the existing authenticated HTTP MCP endpoint:
33
34 ```text
35 http://127.0.0.1:<server-port>/mcp
36 ```
37
38 The provider-visible server key is `t3-code`. The endpoint registers both the
39 preview toolkit and the orchestration toolkit.
40
41 Before `ProviderSessionManager` opens a new V2 provider session, it asks
42 `McpSessionRegistry` for a credential scoped to:
43
44 - the T3 environment;
45 - the parent T3 thread;
46 - the concrete provider instance; and
47 - the provider session.
48
49 The credential grants `preview` and `orchestration` capabilities. Credentials
50 expire after a maximum lifetime, expire when idle, and are revoked when the
51 provider session is released. The raw token is not persisted in orchestration
52 state.
53
54 The MCP HTTP server resolves the bearer token and supplies the resulting
55 `McpInvocationScope` to tool handlers. Orchestration handlers additionally
56 check the `orchestration` capability before reading or mutating state.
57
58 ## Provider Injection
59
60 ### Codex V2
61
62 Codex gets T3's MCP server in each thread's `thread/start`, `thread/resume`,
63 and `thread/fork` config, with the provider-session token in an
64 `Authorization` header. The same server is registered twice:
65
66 - `t3-code`: every tool except `t3_thread_wait` and `delegate_task`.
67 - `t3-code-direct`: only `t3_thread_wait` and `delegate_task`, with
68 `omit_tools_from = ["code_mode", "deferred"]`.
69
70 Code Mode yields a script after about 30 seconds, so the model polls a blocking
71 `t3_thread_wait` or `delegate_task` with `mode: "wait"`, resending its context
72 on each poll. The second entry makes both direct tool calls, like Codex's own
73 wait tools. Codex reports calls as `<server>.<tool>`, so
74 `packages/shared/src/t3McpToolPresentation.ts` must resolve both server names.
75 Tool display and pending-work detection depend on it.
76
77 ### Claude Agent SDK V2
78
79 Claude receives an HTTP MCP server in its query options:
80
81 ```ts
82 {
83 mcpServers: {
84 "t3-code": {
85 type: "http",
86 url: "http://127.0.0.1:<port>/mcp",
87 headers: {
88 Authorization: "Bearer <provider-session-token>",
89 },
90 },
91 },
92 allowedTools: [
93 // existing allowed tools
94 "mcp__t3-code__*",
95 ],
96 }
97 ```
98
99 The adapter logs only whether MCP configuration exists; it does not log the
100 server headers or token.
101
102 ### Cursor Agent SDK V2
103
104 Cursor receives the same authenticated HTTP MCP endpoint through the SDK's
105 `mcpServers` on `Agent.create` / `Agent.resume` and each `send`. With
106 `@cursor/sdk` 1.0.39+, send-level servers replace only the create-time inline
107 set; ambient servers from `settingSources` (`project`, `user`, `team`, `mdm`,
108 `plugins`) stay available. The adapter passes the authorization header to the
109 SDK but projects only redacted option metadata into protocol diagnostics.
110
111 ### Grok ACP V2
112
113 Grok receives the authenticated HTTP MCP endpoint through the ACP
114 `session/new`, `session/load`, and `session/fork` `mcpServers` field. The shared
115 ACP adapter owns standard protocol behavior; the Grok flavor adds xAI extension
116 requests such as structured user questions.
117
118 ACP does not define native subagents or active steering. Grok therefore uses
119 orchestrator-owned child threads and implements steering through
120 cancel-and-restart. Its current driver also lacks `session/fork`, so app forks
121 use portable context transfer. These are orchestrator policies, not
122 provider-specific MCP tools.
123
124 ### ACP Registry V2
125
126 The `acpRegistry` driver is the generic flavor of the same shared ACP adapter.
127 Each provider instance names an agent from the official ACP Registry. Settings
128 searches the registry through the connected server, then prepares a compatible
129 distribution before persisting the provider instance. Binary distributions use
130 a managed, versioned cache; declared checksums are verified when present.
131 Version-pinned `npx` packages install globally through `npm`; `uvx` packages use
132 `uv tool install`. ACP launches the resulting global command directly, so the
133 same command is available for terminal authentication. A local executable may
134 override the installed command without changing the registry-declared arguments
135 or environment.
136
137 Search, preparation, provider status, and session startup share one
138 server-scoped catalog service. This keeps platform selection and registry
139 validation identical across settings and runtime use. Catalog inspection never
140 starts an ACP process, probes models, or performs authentication. The managed
141 provider snapshot creates a disposable `session/new` through the normal provider
142 refresh lifecycle, using success as the authentication-readiness proof and
143 projecting advertised models into the snapshot. Terminal-only login remains a
144 manual operation on the connected server.
145
146 Capabilities such as session loading, session forking, models, modes, and MCP
147 transport are enabled only when the selected agent advertises them. Missing
148 features degrade through V2 policy: steering uses interrupt-and-restart,
149 forking uses portable context when native `session/fork` is unavailable, and
150 subagents use orchestrator-owned child threads. Registry agents do not receive
151 provider-specific extensions; those remain in flavors such as Grok.
152
153 ### Pi V2
154
155 T3 keeps a provider-session HTTP bridge even when Pi supports native MCP.
156 `mcp.json` entries override native registrations, and native MCP's default
157 60-second request timeout can interrupt long-running T3 tools. The bridge owns
158 the injected endpoint and credential and forwards Pi's cancellation signal.
159
160 When a provider session credential exists, the adapter writes a T3-owned
161 extension into the server cache and spawns
162 `pi --mode rpc --extension <cache>/pi-t3-mcp-extension.ts` with:
163
164 ```text
165 T3_MCP_URL=http://127.0.0.1:<port>/mcp
166 T3_MCP_BEARER_TOKEN=<provider-session-token>
167 ```
168
169 The extension preserves public names under `mcp__t3-code__` for saved loadouts
170 and tool selectors. Modern Pi also receives `mcp__t3_code__` aliases, Pi's own
171 name for the server, which reserve it against configured MCP servers. They are
172 `model-only` and hide their own declarations, so the model can call them without
173 added declarations, search results, or codemode entries. An alias follows its
174 public tool: dropped when that tool is excluded, and off while a direct one is
175 off. Pi's `hidden` exposure would make them unreachable. On Pi 0.99+,
176 `orchestrator_capabilities`, `delegate_task`, and `task_status` remain directly
177 available; optional tools are discovered through Pi's builtin `tool_search`.
178 On older Pi or without builtin search, all tools remain directly available.
179 The bridge calls the original MCP tool name over HTTP. Follow-up requests send
180 `mcp-protocol-version: 2025-06-18`; Effect's MCP transport returns 400
181 without it. The first turn of a session also receives the shared T3
182 orchestration instructions.
183
184 Pi keeps ownership of native extension discovery. T3 does not replace Pi's
185 `subagent` tool or reproduce Pi's package and project-trust loader. Durable
186 delegation goes through the namespaced T3 MCP `delegate_task` tool and the
187 shared orchestration child-thread lifecycle. When Pi's example `subagent`
188 extension is installed, the adapter observes its documented `details.results`
189 shape and projects task cards with no child thread id. Unknown result shapes
190 remain ordinary dynamic tool output.
191
192 ### Provider Support
193
194 A provider instance can run child tasks when its live `ProviderInstance`
195 exposes a V2 `orchestrationAdapter` — the same registration the orchestrator
196 resolves when a `delegated_task.request` executes. That covers Codex, Claude
197 Agent SDK, Cursor Agent SDK, Grok, generic registry agents over ACP, OpenCode,
198 OpenCode 2, Pi, Antigravity, and any future driver that builds an adapter.
199 Capability discovery still reports other registered provider instances, but
200 marks them unavailable for orchestration when no adapter resolves. This keeps
201 provider selection model-visible without allowing a request that cannot run.
202
203 ## Tool Surface
204
205 `OrchestratorToolkit` in
206 [`toolkits/orchestrator/tools.ts`](../../apps/server/src/mcp/toolkits/orchestrator/tools.ts)
207 is the authoritative list of orchestration tools. The sections below cover
208 delegation and thread tools. `t3_thread_launch` is documented with them but
209 registered by the project toolkit in
210 [`toolkits/project/tools.ts`](../../apps/server/src/mcp/toolkits/project/tools.ts).
211
212 ### `orchestrator_capabilities`
213
214 Returns:
215
216 - the inherited provider instance and model;
217 - the parent runtime and interaction modes;
218 - registered provider instances and advertised models;
219 - whether each provider can run a child task; and
220 - feature flags for polling, cancellation, and batch thread creation.
221
222 Unavailable providers include model-visible constraints such as missing V2
223 adapter support, disabled state, missing executable, or missing authentication.
224
225 The model list is short on purpose: catalogs such as OpenCode can hold hundreds
226 of models, and every call lands in the agent's context. Each provider lists
227 custom, favorite, and the caller's own models, plus all current (non-legacy)
228 models for Codex, Claude, Muse, and Grok, or the first 8 current models in the
229 user's model order for other providers. `omittedModels` counts the rest, and the
230 `search` input finds them, legacy models included. `delegate_task` still accepts
231 any catalog model.
232
233 ### `delegate_task`
234
235 Creates a T3-owned child thread and immediately dispatches the supplied task
236 prompt.
237
238 The [shared contract](../../packages/contracts/src/orchestratorMcp.ts) is authoritative for
239 inputs and results, including target options and linked-environment fields.
240
241 ```ts
242 import type {
243 OrchestratorMcpDelegateTaskInput as DelegateTaskInput,
244 OrchestratorMcpDelegateTaskResult as DelegateTaskResult,
245 } from "@t3tools/contracts";
246 ```
247
248 For local delegation, provider, model, runtime mode, and interaction mode inherit
249 from the parent when omitted. A driver-only target inherits the parent's provider instance
250 when it can run child tasks, and otherwise selects an available instance of
251 that driver; an explicit `providerInstanceId` is honored exactly and fails
252 when unavailable. Selecting a different provider without a model uses that
253 provider's first advertised model.
254
255 Set `target.options` using the options returned by `orchestrator_capabilities`, such as
256 `{effort: "max"}`. Supplied values override inherited selections; `{}` or `[]` clears them.
257 For local delegation, use `isolation: "worktree"` for a separate prepared checkout from
258 the parent's commit; the default `"shared"` uses the parent's checkout. Uncommitted parent
259 edits are not copied. A linked-environment target (`target.environmentId`) runs in the remote
260 project's checkout and rejects worktree isolation. To launch an isolated thread there, use
261 `t3_thread_launch` with `environmentId` and a worktree `workspaceStrategy`.
262
263 A provider runs a runtime mode it does not offer as `approval-required`, so a
264 child would ask for approval on every command. `orchestrator_capabilities`
265 lists `runtimeModes` only for a provider that offers some of the modes, and
266 omits it for a provider that offers all of them. When the target lists
267 `runtimeModes`, an explicit `runtimeMode` outside that list is refused, and an
268 inherited mode steps down to the broadest mode the target offers.
269
270 Each independent delegated review round uses a new `delegate_task` call with the
271 original brief, prior findings, responses, and unresolved objections. Track each
272 round by its own `taskId` and use a distinct `clientRequestId` per round, stable
273 across retries of that round.
274 A follow-up that needs the same child's conversation goes through `t3_thread_send`
275 on its `childThreadId`. After the original task completes, that follow-up runs as a
276 fresh task in the child thread; it does not reopen the completed task or change its
277 published result.
278
279 Delegation requires an active parent run owned by the MCP credential's
280 provider session. The request becomes the V2 command
281 `delegated_task.request`.
282
283 `mode: "async"` returns the current durable state immediately.
284 `mode: "wait"` waits for the task result, including nested work and completion follow-ups, or until
285 the timeout expires. A wait timeout does not cancel the child; the result sets
286 `waitTimedOut: true`. When the result includes `next`, completion wakes the parent:
287 do not wait on the task or poll it; continue other work, and end the turn when none is
288 left. A pending blocking question also ends the wait with `hasPendingQuestion: true` and
289 `waitTimedOut: false`.
290 If `hasPendingQuestion`, pass `threadId=childThreadId` to `t3_pending_request` with
291 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
292 task's own unfinished work also ends the wait. Its identity appears in `pendingApproval`;
293 it grants no approval authority. Read the fresh full request in the child thread before
294 responding, since the durable record can outlive its provider callback. Async questions
295 do not end the wait.
296
297 ### `task_status`
298
299 Reads a delegated task from the parent thread's durable projection. A task ID
300 from another parent thread is rejected. `childRunId` identifies the original
301 run. `status: "starting"` means the child's provider has not started its turn
302 yet, so a task that stays there has not begun work. A task in a linked
303 environment reads its run's status there for this. `workState` distinguishes
304 active work, a finished turn waiting for children, and an available result. The
305 task remains nonterminal until its known work finishes. Its published `summary`
306 and result transfer then remain stable across later follow-ups.
307 `hasPendingChildRuns` reports later queued or executing turns; `latestTerminal*`
308 exposes later executed, non-monitor results without replacing the published task
309 result.
310
311 ### `task_cancel`
312
313 Stops every task the child delegated, then the child thread with the internal
314 `thread.stop` command, cancels the task's own queued turn, and disposes automatic
315 parent delivery. Like a user Stop, `thread.stop` interrupts the running turn, holds
316 queued turns, and ends pull request watches. The task's own queued turn is cancelled
317 even if Stop already held it, so a task that is only queued can be cancelled; other
318 queued turns in the child stay held for Resume. A nonterminal task is rejected when
319 it has no interruptible run, no queued turn of its own, and its finished turn no
320 longer waits on background work or delegated tasks. Once a cancelled task's turn
321 ends, a completed result settles as `interrupted` and a failed one stays `failed`. A
322 terminal task returns its existing status, and its child thread still stops,
323 including later runs and watch wakes. In both cases, a follow-up that lost its child
324 run but still shows as running on the parent is cancelled there and reported as
325 `cancelled`. Published task results remain available. It accepts an
326 optional cancellation reason.
327
328 ### `create_threads`
329
330 Creates between one and twenty ordinary top-level T3 threads:
331
332 ```ts
333 import type { OrchestratorMcpCreateThreadsInput as CreateThreadsInput } from "@t3tools/contracts";
334 ```
335
336 Each entry independently resolves provider, model, and modes. The new threads
337 inherit the parent's project, branch, and worktree path, but they have no
338 sub-agent lineage. Entries with a prompt immediately dispatch a run; entries
339 without a prompt remain idle. `create_threads` is local-only: `target.environmentId` and
340 `target.projectId` are ignored even though the shared target contract accepts them. Use
341 `t3_thread_launch` with `environmentId` and `projectId` to select another environment or project.
342
343 ### `t3_thread_launch`
344
345 Launches one ordinary top-level thread through the app's launch service. Use an
346 explicit `workspaceStrategy` to create a new worktree (`worktree` with `baseRef`),
347 attach an existing checkout (`existing_worktree` with `worktreePath`), or use the
348 project root (`root`, also the default). The thread is bound to that workspace
349 before the agent starts. Creating a worktree in the task prompt does not update
350 this binding.
351
352 Pass the task in `message`. Project, model, and modes inherit when omitted;
353 workspace does not. `scratch: true` launches without a project, in a folder of
354 its own under the environment's Scratch project. A new worktree with `startFromOrigin` omitted follows the new-worktree setting. For stacked PRs, use the parent branch as `baseRef` with
355 `startFromOrigin: false`. The new thread may not run with broader runtime or
356 interaction modes than the caller. As for `delegate_task`, a runtime mode the
357 provider does not offer is refused, and an inherited or default one steps down
358 to the broadest mode it offers. `create_threads` remains the batch option for a
359 shared checkout.
360
361 Set `clientRequestId` on the initial launch to make it retryable. After an error
362 or a lost reply, resend the same request with the same key from the same
363 provider session. This reuses any thread already created by that request. If the
364 initial request had no key, check for the thread before launching again.
365
366 ### `t3_thread_list`
367
368 Lists durable thread shells in one project, newest first: `projectId` when
369 given, else the calling thread's project. Callers can filter by title, run
370 status, and whether app-owned sub-agent threads are included. Results are
371 bounded and offset-paginated. Deleted threads are never listed.
372
373 ### `t3_thread_read`
374
375 Reads the durable state, recent runs, and visible timeline of any thread in
376 the environment by thread ID. A deleted thread returns `thread_not_found`. The
377 default `messages` view returns user messages, assistant
378 messages, and proposed plans. The `activity` view also returns summarized tool,
379 reasoning, checkpoint, handoff, and runtime-request items. Large item text is
380 bounded and reports whether it was truncated. An agent in a T3 thread that
381 reads without a cursor gets the newest items, and `beforePosition=earlierPosition`
382 reads older ones. Client callers (the CLI, linked environments, outside MCP
383 clients) start at the oldest item instead, because the CLI and linked
384 environments on older versions read that way and follow only `hasMore`.
385 `afterPosition=-1` starts any read at the oldest item, and
386 `afterPosition=nextPosition` reads newer items. The server stops adding items once the result reaches about 30,000 characters and
387 reports the rest through `earlierPosition` or `hasMore`. Claude Code saves MCP
388 results over its token limit to a file instead of showing them, so a read has
389 to fit whatever `limit` an agent asks for.
390
391 Thread and message results include required `createdBy` and `creationSource`
392 provenance. MCP-created threads and user-role messages use `createdBy: "agent"`
393 and `creationSource: "mcp"`; provider output uses `creationSource: "provider"`.
394 Actor and ingress are separate so agent-authored user-role messages remain
395 distinguishable from human-authored messages.
396
397 Agents mention another thread by the `link` its result carries,
398 `<t3-thread://v2/<environmentId>/<threadId>>`, so they never format an id or
399 write a title, which goes stale when the user renames the thread. The
400 environment that owns the thread builds the link, so forwarded results and tasks
401 delegated to a linked environment name that environment. Clients open only that
402 environment's thread and show its current title; a link to a thread they do not
403 know renders as a label that opens nothing. Older `t3-thread://v1/<threadId>`
404 links name no environment: clients resolve them in the message's environment,
405 then by a unique match in another enabled environment. An outside OAuth client,
406 one that is not a linked environment, cannot render `t3-thread://` links, so it
407 gets the link Copy thread copies, `https://app.t3.codes/threads/<environmentId>/<threadId>`
408 on the server's `T3CODE_HOSTED_APP_URL`, for threads in this environment. The
409 hosted app offers the desktop app, the mobile app, or itself.
410
411 List and read results report `snoozed`, `snoozedUntil`, and `pinned`, and
412 `t3_thread_list` filters on `snoozed`. The server's `isSnoozed` follows the
413 client's `effectiveSnoozed`, so agents and the sidebar agree: a snoozed thread
414 wakes early only when it has a pending request or fails after snoozing. Completed
415 runs, background wakes, and delegated completions keep it snoozed.
416
417 They also report `blockedOnThreadWait` and `pendingBackgroundTasks`, the shell
418 fields behind the sidebar's Waiting label, so an agent can see what a thread
419 still waits on after its run completed. A subagent or `background_task` holds
420 the thread. A command or monitor holds it only with `awaited: true`, since agents
421 often leave a dev server running.
422
423 ### `t3_thread_update`
424
425 Updates metadata for the calling thread or any other thread in the environment.
426 The typed actions are `rename`, which requires `title`, and `regenerate_title`,
427 which rejects one. Pull request links go through the separate
428 `link_pull_request` and `unlink_pull_request` tools. Branch and workspace
429 changes are outside this tool.
430
431 The result includes the command ID and durable event sequence together with the
432 resultant title, title-regeneration marker, and linked pull request. Reusing a
433 `clientRequestId` for the same action and thread replays the same command
434 receipt. Thread list and read results expose the linked pull request, and thread
435 detail also exposes an in-flight title regeneration.
436
437 ### `t3_thread_send`
438
439 Sends a message to any ordinary or delegated thread in the environment:
440
441 - `auto` starts an idle thread, steers a fully active turn, or queues behind a
442 turn that is not yet steerable;
443 - `queue` creates a separate follow-up run after active work;
444 - `steer` requires a steerable active provider turn; and
445 - `restart` requires an active provider turn and uses the orchestrator's
446 interrupt-and-restart path. On a provider that can stop a turn and queue
447 messages but not restart a turn with new input, it stops the turn and queues
448 the message ahead of other queued messages; an unheld delegated-task result
449 that survives the stop still runs first. It is rejected when neither path
450 applies: the provider cannot stop a turn, Stop has already reached the turn,
451 or the turn or the new message is `/compact` or `/logout`.
452
453 The target runtime and interaction modes may not be broader than the caller's.
454 Stable command and message IDs are derived from `clientRequestId` for
455 idempotent retries.
456
457 `outputSchema` (also on `t3_thread_launch`) asks the run for a result as data.
458 The run stores the schema, the turn's prompt ends with how to hand the result
459 back, and the agent calls `t3_submit_output`. The server checks the value
460 against the schema before storing it, so the caller never parses a reply. A send
461 that asks for a result is queued instead of steered: the result belongs to one
462 whole turn. A turn can end without submitting; the caller sees a finished run
463 with no `output`.
464
465 ### `t3_submit_output`
466
467 Stores the calling thread's result on its running turn, once it fits the schema
468 that turn was sent with. A turn that was asked for nothing answers for the
469 newest turn that was asked and has not answered yet, which is how an agent that
470 ended its turn to wait gives its result after it is woken. A rejection names what did not fit, so the agent can
471 correct it and call again; a later accepted submission replaces an earlier one.
472
473 ### `t3_thread_wait`
474
475 Waits for a selected run to become `completed`, `failed`, `cancelled`,
476 `interrupted`, or `rolled_back`. Without `runId`, it pins the latest run at call
477 time; an idle thread returns immediately. A timeout reports the latest durable
478 status and does not cancel work. `output` carries what the run submitted
479 against its `outputSchema`; with `untilOutput`, a completed run that has not
480 submitted yet is waited on until it has.
481
482 ### `t3_thread_interrupt`
483
484 Interrupts a selected active run through the normal V2 `run.interrupt` command.
485 Without `runId`, it selects the newest interruptible run. A terminal run is
486 returned unchanged, and a thread with no active provider turn returns
487 `no_active_run`.
488
489 ### Scheduled tasks
490
491 `schedule_task`, `list_scheduled_tasks`, and `delete_scheduled_task` manage
492 recurring work in the app scheduler; `schedule_task` with a `scheduledTaskId`
493 updates an existing task. A schedule
494 runs its prompt on an interval, at a fixed time in the server's local time
495 zone, or on each qualifying webhook request, even when no turn is active.
496 Without a signature, anyone with the webhook URL can trigger a run.
497 Signature checks, filters, and dedupe can skip a webhook request.
498 `bindToCurrentThread` defaults to `true` only when the caller has a thread in
499 the task's project; otherwise it defaults to `false`. Bound runs post into
500 that thread; unbound runs each launch a fresh thread in the task's project.
501 Explicit `bindToCurrentThread: true` without a caller thread in that project
502 is rejected. Pausing uses `schedule_task` with `scheduledTaskId` and `enabled: false`;
503 deletion is permanent.
504
505 ## Delegated Task Lifecycle
506
507 The MCP server is a command ingress into V2. It does not call provider adapters
508 directly.
509
510 ```text
511 provider model
512 -> MCP tools/call delegate_task
513 -> authenticated OrchestratorMcpService
514 -> shared ThreadManagementService
515 -> V2 delegated_task.request command
516 -> child thread + child run
517 -> parent app_owned subagent projection
518 -> parent/child execution nodes
519 -> consumed subagent_spawn context transfer
520 -> normal provider effect and runtime ingestion
521 -> child run reaches a terminal state
522 -> parent subagent/node/turn item finalized
523 -> consumed subagent_result context transfer
524 -> wait result or later task_status result
525 ```
526
527 The child thread has lineage relationship `subagent` and points back to the
528 parent node. The parent gets an `app_owned` sub-agent projection and a
529 sub-agent turn item so the existing debug UI can render progress.
530
531 Terminal provider events trigger finalization. The event stream first replays
532 persisted events and then follows live events, so finalization also runs after
533 a server restart. An existing `subagent_result` transfer makes finalization
534 idempotent.
535
536 Users rarely watch child threads, so a child question would otherwise go
537 unanswered. When a child opens a pending `user_input` request, the parent gets
538 a notification message telling it to answer with the pending request tools or
539 ask the user. The message says whether the child is blocked or, for a Codex
540 async question, still working. If the parent's turn is running and its provider
541 can steer without interrupting tools, the notification steers into that turn,
542 like a background task's completion. A queued notice would wait behind a
543 long-running orchestrator turn that may never end. Otherwise it queues. If the
544 question is answered or dismissed before a queued notification starts a turn,
545 that queued turn is cancelled. Approvals are not
546 routed, because those tools cannot answer them.
547 A parent still blocked in a `delegate_task` wait gets the blocking question
548 through that wait instead.
549 If the provider cuts that wait short, a still-pending live question wakes the
550 parent when its launching run completes, fails, or waits for post-turn work.
551 Stopping or interrupting the parent prevents this catch-up.
552
553 A failed run exposes its provider error before any progress text. Successful
554 results use the latest assistant content from the final work turn.
555
556 ## Policy And Idempotency
557
558 - A child runtime mode may stay equal to or become narrower than the parent
559 mode. It may not escalate privileges.
560 - A child interaction mode may stay equal to or narrow from `default` to
561 `plan`. It may not escalate from `plan` to `default`.
562 - Thread tools take any thread in the environment as a target. For a thread
563 caller, list and search cover one project: its own unless `projectId` is given.
564 - A tool that changes another thread needs the calling thread's live run, and
565 the target's runtime and interaction modes may not be broader than the
566 caller's. This is the same privilege ceiling as child creation.
567 - Provider instances must be enabled, installed, available, authenticated, and
568 backed by a V2 adapter.
569 - A requested model must be advertised by the selected provider when the
570 provider publishes a model list.
571 - `clientRequestId` derives stable command, thread, and message IDs within the
572 provider session. Retrying the same call returns the same durable work.
573 - Calls without `clientRequestId` receive a generated request key and create
574 new work.
575
576 Expected denials use the typed `OrchestratorMcpFailure` result:
577
578 ```text
579 capability_denied
580 parent_not_active
581 provider_unavailable
582 model_unavailable
583 runtime_mode_escalation_denied
584 interaction_mode_escalation_denied
585 task_not_found
586 task_not_cancellable
587 thread_not_found
588 run_not_found
589 thread_not_sendable
590 thread_not_interruptible
591 invalid_request
592 orchestration_error
593 ```
594
595 ## Code Ownership
596
597 - Shared schemas: `packages/contracts/src/orchestratorMcp.ts` and
598 `packages/contracts/src/threadMetadataMcp.ts`
599 - MCP services: `apps/server/src/mcp/OrchestratorMcpService.ts` and the focused
600 `apps/server/src/mcp/ThreadMetadataMcpService.ts`
601 - Tool definitions and handlers:
602 `apps/server/src/mcp/toolkits/orchestrator/`
603 - HTTP registration and authentication:
604 `apps/server/src/mcp/McpHttpServer.ts`
605 - Credential lifecycle: `apps/server/src/mcp/McpSessionRegistry.ts`
606 - Provider injection:
607 `apps/server/src/orchestration-v2/ProviderSessionManager.ts` and V2 adapters
608 - Durable delegated-task command and finalization:
609 `apps/server/src/orchestration-v2/Orchestrator.ts`
610
611 ## Verification
612
613 The integration test uses the real MCP toolkit registration, V2 orchestrator,
614 SQL persistence, event ingestion, projections, and checkpoints. Only the
615 external provider adapters are deterministic test implementations.
616
617 Coverage includes:
618
619 - capability discovery;
620 - cross-provider delegated completion;
621 - prompt-only child context;
622 - parent and child lineage projections;
623 - spawn and result context transfers;
624 - async status polling;
625 - cancellation;
626 - batch ordinary-thread creation;
627 - thread listing and timeline reads, including another project's threads;
628 - ordinary-thread send, wait, steering, and interruption;
629 - inheritance and per-thread provider overrides; and
630 - idempotent retries.
631
632 Provider adapter tests separately verify Codex, Claude, Cursor, Grok, and ACP
633 Registry behavior and MCP injection. The provider-session manager test verifies
634 that credentials exist before an adapter opens and are revoked when it closes.