Per-thread environment on t3_thread_launch for external orchestrators

[arthurcruzd]

Problem or use case

An external orchestrator can now drive T3 through the V2 /mcp client. It launches many threads in one project with t3_thread_launch and workspaceStrategy: existing_worktree, each in its own worktree for its own task.

Each of those agents needs a few task-scoped values in its process environment:

• the task id
• the path of its task inbox
• a per-task temp directory
• a git core.hooksPath override, set through GIT_CONFIG_COUNT/GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n

Tools, hooks and scripts the agent runs read these, not only the model.

t3_thread_launch takes no environment, and provider processes inherit the T3 server's. So two threads in the same project cannot get different values.

The concrete consumer is Firstmate (kunchenguid/firstmate#6904). On 0.0.46 nightly we ran its whole worker lifecycle through /mcp: launch into an existing worktree, steer, wait, interrupt, archive, and restart. This was the one gap left.

The workarounds it forces today:

• Put the values in the launch message. The model sees them, but tools and git hooks that read the environment do not.
• Write per-provider settings into the worktree, for example the env block in .claude/settings.local.json. This only works for Claude, and it writes into the user's checkout.
• Use a wrapper binaryPath per provider instance that looks values up by cwd. This is fragile, and one Codex app-server serves every Codex thread, so a wrapper cannot vary by thread.

Neighboring ideas, not duplicates:

• [Feature]: Per-project environment variables #6715 asks for per-project, user-defined, static environment.
• Expose thread lineage to delegated children in the launch env (T3_THREAD_KIND / T3_PARENT_THREAD_ID / T3_TASK_ID) #12286 asks for T3-generated lineage variables for delegated children.

Here, the caller supplies the values per launch, and they differ between threads in one project.

Proposed solution (narrowest shape)

• Field. An optional env: Record<string, string> on t3_thread_launch.
• Thread-scoped. Apply it to that thread's provider process, including provider restarts of that thread:
  • Claude: merge it into the per-session env the adapter already passes to the SDK.
  • Codex: since one app-server serves all threads, the per-thread config (for example shell_environment_policy.set) looks like the natural carrier, though I'd defer to you on that.
• Allowlisted. Use a key pattern plus a fixed denylist for anything that changes execution or identity: PATH, HOME, NODE_OPTIONS, LD_*/DYLD_*, provider home and auth variables such as CLAUDE_CONFIG_DIR, CODEX_HOME and *_API_KEY. Cap the number of keys and the value length.
• Never persisted. Keep it in memory with the provider session, out of the event store, transcripts, checkpoints and logs. t3_thread_read shows key names at most.
• Secret-safe. Values never appear in activity items or errors.
• Ceiling-gated. Only orchestration:operate credentials with a non-read-only ceiling may set it.

Open question: because it is not persisted, a T3 restart drops it. Accepting the same env on t3_thread_configure would let the caller re-apply it before the next send. I'd welcome a better idea.

Alternatives considered

• Per-project environment ([Feature]: Per-project environment variables #6715). It cannot vary per thread within one project.
• Persisting the overlay with the thread. The restart story is simpler, but caller-supplied values are then stored at rest.
• Leaving this to callers. That is the workaround list above, which is uneven across providers.

Offer

If you approve the direction and scope, I'm happy to open a PR. If you'd rather implement it differently, that works too.

This write-up was drafted with my AI agent on my behalf.

[kaankolcu]

Another use case for this: a coordinator thread on a laptop drives worker agents on cloud VMs (Boat sandboxes). Each VM can already be a T3 environment through the desktop's SSH route, which installs the matching server by itself. But MCP tools act only on "this environment", so the coordinator cannot start a worker thread on a VM, read it, or be woken when it ends. Today it drives the VMs through their CLI from background shells, and those workers are invisible in T3. An environment target on t3_thread_launch and delegate_task, plus cross-environment t3_thread_read/t3_thread_wait, would make each VM a normal, visible T3 worker. Exposing the Auto balance choice to MCP and a CLI to add SSH environments (t3 env add ssh <host>) would cover a VM fleet. (Posted #19309 before finding this one; closing it as a duplicate.)