Skip to content

Commit 15de39e

Browse files
docs(server): agents learn they may launch within their own modes
The t3_thread_launch description, the orchestration instructions every agent gets, and the orchestrator MCP doc still said launching needs a full-access/default caller. Since the access declarations, any caller with a live turn launches at its own modes or below, so Supervised agents were told not to try something that works. t3_thread_read also says why it stays a read although it acknowledges a child's delivered result. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent ce8a596 commit 15de39e

4 files changed

Lines changed: 7 additions & 4 deletions

File tree

‎apps/server/src/mcp/toolkits/orchestrator/handlers.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,9 @@ const handlers = {
8787
return yield* service.listThreads(scope, input);
8888
}),
8989
),
90+
// Reading a child's finished result also acknowledges its delivery to the
91+
// reader's own thread. That is bookkeeping on the caller's own subagent, not
92+
// a change to anything it reads, so this stays a read.
9093
t3_thread_read: McpToolAccess.reads((input) =>
9194
Effect.gen(function* () {
9295
const scope = yield* McpInvocationContext.McpInvocationContext;

‎apps/server/src/mcp/toolkits/project/tools.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ const ProjectCloneTool = Tool.make("t3_project_clone", {
103103
const ThreadLaunchTool = Tool.make("t3_thread_launch", {
104104
...shared,
105105
description:
106-
'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. For upstream commits, 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. After errors or lost responses, inspect t3_thread_list before retrying. Attachments must be pending uploads. Requires a full-access/default calling thread; a caller outside a T3 thread launches up to its approved permission mode.',
106+
'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. For upstream commits, 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. 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.',
107107
parameters: Schema.Struct({
108108
projectId: Schema.optional(ProjectId),
109109
scratch: Schema.optional(

‎apps/server/src/provider/T3OrchestrationInstructions.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ For independent implementation or a PR stack in its own worktree, use \`t3_threa
2020
- Existing worktree: \`{"title":"Continue cleanup","workspaceStrategy":{"type":"existing_worktree","worktreePath":"/absolute/path/to/worktree","branch":"feature/ui-cleanup"},"message":"Continue the cleanup."}\`
2121
- Project's main checkout: \`workspaceStrategy:{"type":"root"}\`. Omitting workspaceStrategy also selects root; it does not inherit the caller's worktree.
2222
23-
For stacked work, set \`baseRef\` to the intended parent branch and \`startFromOrigin:false\` to use its local commits. Use \`startFromOrigin:true\` when you intend to fetch and start from origin. Uncommitted edits are not copied. Use \`t3_worktree_list\` to discover existing checkout paths. Project, model selection, and modes inherit unless supplied; launch requires a full-access/default caller.
23+
For stacked work, set \`baseRef\` to the intended parent branch and \`startFromOrigin:false\` to use its local commits. Use \`startFromOrigin:true\` when you intend to fetch and start from origin. Uncommitted edits are not copied. Use \`t3_worktree_list\` to discover existing checkout paths. Project, model selection, and modes inherit unless supplied; a launched thread may not run with broader modes than yours.
2424
2525
\`t3_thread_launch\` is the single-thread launch tool. Use \`create_threads\` only for a batch of threads intentionally sharing the caller's checkout: it always inherits the caller's project, branch, and worktree and has no workspace override. Asking an agent to run \`git worktree add\` or \`cd\` in its prompt does not update T3's thread binding. Select the workspace in the launch call instead. \`t3_worktree_handoff\` moves the calling thread, not another thread, and cannot move a thread already attached to a worktree.
2626

‎docs/orchestration-v2/orchestrator-mcp-server.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -325,8 +325,8 @@ this binding.
325325
Pass the task in `message`. Project, model, and modes inherit when omitted;
326326
workspace does not. `scratch: true` launches without a project, in a folder of
327327
its own under the environment's Scratch project. For stacked PRs, use the parent branch as `baseRef` with
328-
`startFromOrigin: false`. Launch requires a full-access/default caller and has
329-
no retry key, so inspect existing threads after a failed or lost response before
328+
`startFromOrigin: false`. The new thread may not run with broader runtime or
329+
interaction modes than the caller. Launch has no retry key, so inspect existing threads after a failed or lost response before
330330
launching again. `create_threads` remains the batch option for a shared checkout.
331331

332332
### `t3_thread_list`

0 commit comments

Comments
 (0)