feat(server): add Codex thread start MCP tool

[D3OXY]

Summary

Adds a provider-scoped MCP tool, t3_thread_start, that lets Codex start another T3 Code thread only when the user explicitly asks to start, spawn, or create another thread/agent.

This keeps the tool available for intentional multi-thread workflows without encouraging autonomous delegation or background parallel work.

What changed

• Registers a new thread MCP toolkit with t3_thread_start.
• Adds a thread-management MCP capability and grants it to provider-scoped MCP sessions.
• Supports three start modes:
  • new_worktree: creates a temporary branch/worktree from the default branch by default.
  • existing_worktree: starts a thread in a supplied worktree path.
  • current_checkout: starts a thread on the current checkout and returns warning metadata.
• Inherits model/runtime/interaction settings from the source thread unless the tool call overrides them.
• Updates Codex developer instructions so this tool is used only after explicit user intent, not for autonomous delegation.

Implementation notes

• Extracts bootstrap turn-start handling from the WebSocket route into BootstrapTurnStartDispatcher.
• The shared dispatcher owns thread creation, optional worktree preparation, setup-script launch, cleanup on bootstrap failure, and VCS status refresh.
• WebSocket dispatch and MCP tool dispatch now share the same bootstrap path instead of duplicating orchestration/worktree behavior.
• MCP route registration stays lightweight; runtime-only services are registered for the server lifetime so tool registration does not leak git/projection/orchestration dependencies into HTTP route construction.

Validation

• vp check
• vp run typecheck

Risk

Moderate. This touches thread-start orchestration and WebSocket bootstrap routing, but the behavior is centralized behind the same command shape and covered with new thread-tool tests plus existing server type coverage.

Note

Add t3_thread_start MCP tool for starting Codex child threads

• Defines a new MCP tool (t3_thread_start) in tools.ts with validated input/output schemas supporting new_worktree, existing_worktree, and current_checkout modes.
• Implements the handler in handlers.ts: resolves source project/thread, prepares worktrees, and dispatches thread.turn.start via a new BootstrapTurnStartDispatcher.
• Extracts bootstrap orchestration (worktree creation, remote fetch, setup script, activity logging) from ws.ts into the centralized BootstrapTurnStartDispatcher service.
• Registers the thread toolkit and dispatcher on server startup; adds thread-management to the MCP capability set so bearer tokens authorize the new tool.
• Adds t3_thread_start usage guidance to Codex developer instructions in CodexDeveloperInstructions.ts.

^{Macroscope summarized 3ae43a2.}

---

Note

Medium Risk
Touches thread creation, git worktrees, and orchestration bootstrap paths shared by WebSocket and MCP; behavior is centralized but still mutating and capability grants on all new MCP tokens may affect downstream checks.

Overview
Introduces t3_thread_start on the T3 Code MCP server so Codex can spawn child threads when the user explicitly asks. Provider MCP sessions now include a thread-management capability (alongside preview), and the tool requires it at invocation time.

The tool supports new_worktree (default), existing_worktree, and current_checkout modes, inherits model/runtime/interaction settings from the invoking thread unless overridden, dispatches a bootstrapped thread.turn.start immediately, and returns launch metadata (with a warning for same-checkout starts) without waiting for the child to finish.

Bootstrap turn-start logic (thread create, optional worktree prep, setup script, failure cleanup, VCS refresh) is extracted from ws.ts into BootstrapTurnStartDispatcher, shared by WebSocket orchestration dispatch and the MCP handler. Server startup registers the dispatcher and thread-start runtime alongside MCP toolkit registration.

Codex plan and default developer instructions now document when t3_thread_start may be used (explicit user intent only, not autonomous delegation).

^{Reviewed by Cursor Bugbot for commit 3ae43a2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 85f702bd-6f18-47c8-96e7-f169c04b6de2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new MCP tool for spawning child threads - a significant new capability. Additionally, there are unresolved medium-severity review comments identifying potential race conditions and incorrect output behavior that warrant human attention.

^{You can customize Macroscope's approvability policy. Learn more.}

[D3OXY]

#2829

[juliusmarminge]

we can get this in before #2829 :)

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 3ae43a2. Configure here.}

[cursor]

MCP bypasses startup command gate

Medium Severity

The t3_thread_start handler directly calls BootstrapTurnStartDispatcher.dispatchActive. This bypasses the command queuing mechanism that ensures server readiness for WebSocket commands. Consequently, MCP thread starts can execute prematurely during startup, risking race conditions and inconsistent orchestration compared to WS.

 

^{Reviewed by Cursor Bugbot for commit 3ae43a2. Configure here.}

[cursor]

Setup script ignored existing worktree

Low Severity

The runSetupScript flag is only passed to BootstrapTurnStartDispatcher when mode is new_worktree. It's incorrectly nested within the prepareWorktree object, which is only created for new_worktree mode. This prevents setup scripts from running for existing_worktree threads, even when runSetupScript is specified in the input.

 

^{Reviewed by Cursor Bugbot for commit 3ae43a2. Configure here.}

[cursor]

New worktree path omitted from output

Medium Severity

For new_worktree, the handler keeps worktreePath as null in the tool response even though dispatchActive completes worktree creation and updates thread metadata with the real path. Codex is told the child has no worktree path after a successful start.

 

^{Reviewed by Cursor Bugbot for commit 3ae43a2. Configure here.}