[Feature]: Allow worktree setup scripts to block the first agent turn until completion

[amogower]

Before submitting

• I searched existing issues and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/server

Problem or use case

A project action with runOnWorktreeCreate: true is started after the worktree is created, but T3 Code launches the first agent turn immediately after writing the setup command to its terminal.

The agent can therefore begin inspecting or modifying the worktree while the setup script is still:

• cloning child repositories
• installing dependencies
• copying local environment files
• generating code
• creating symlinks
• allocating ports
• starting local infrastructure

This creates a race condition. For example, an agent may report that a repository or generated file is missing simply because setup has not cloned or generated it yet. In a monorepo, the agent can also run package-manager or Git commands against a partially initialized workspace.

I reproduced this with T3 Code 0.0.31. The current ProjectSetupScriptRunner returns status: "started" after opening the terminal and writing the command; the first provider turn is then dispatched without observing the setup command's completion.

Proposed solution

Add an opt-in blocking mode for automatic worktree setup actions. The exact property name is flexible, but conceptually:

{
  "name": "Set up worktree",
  "command": "bash scripts/setup-worktree.sh",
  "runOnWorktreeCreate": true,
  "waitForCompletion": true
}

When enabled, T3 Code would:

1. Create the worktree.
2. Launch the setup action in its dedicated terminal.
3. Display setup progress normally.
4. Wait for the setup command's exit status before dispatching the first agent turn.
5. On exit code 0, record completion, close the setup terminal, and start the agent.
6. On a non-zero exit, leave the terminal open with its output and keep the agent paused.

The failure state could offer "Retry setup" and "Continue anyway" actions.

The existing non-blocking behavior could remain the default when the new option is absent, preserving compatibility.

Why this matters

Worktree setup commonly establishes files, repositories, dependencies, and services that the agent assumes exist when interpreting the task.

Blocking the first turn until setup succeeds would make new worktrees deterministic and prevent agents from reasoning about or modifying partially initialized workspaces. This is particularly important for monorepos and projects whose setup takes more than a few seconds.

Smallest useful scope

The smallest useful implementation would support one automatic setup action that:

• optionally blocks the first agent turn
• detects successful or failed command completion
• starts the agent only after success
• leaves failed setup output available for diagnosis

Retry controls, configurable timeouts, and multiple blocking actions could come later.

Alternatives considered

• Git post-checkout hook: This blocks git worktree add, but its output is currently difficult to observe in T3 Code and it runs outside the project-action lifecycle. Related: feat: Surface post-checkout hook output during worktree creation #551.
• A readiness file plus agent instructions: A hook can create a pending marker and instruct the agent to wait for it, but this relies on every provider obeying repository instructions and duplicates orchestration that T3 Code already owns.
• Appending && exit to the setup command: This closes the successful setup terminal, but it does not prevent the agent from starting while setup is running.
• Performing setup before opening T3 Code: This removes much of the benefit of automatic per-worktree setup.

Risks or tradeoffs

• A hanging setup script could delay the first turn indefinitely. The UI should expose elapsed time and a cancel or "Continue anyway" action.
• Blocking setup increases perceived thread-start latency, although it avoids starting an agent in a workspace that is not ready.
• Setup commands remain a repository trust boundary. This proposal is complementary to, but separate from, [Feature]: Allow checked-in t3.json setup actions to run without per-user import #5063.

Examples or references

Related but distinct issues:

• feat: Surface post-checkout hook output during worktree creation #551 — surface post-checkout hook output
• [Feature]: Allow checked-in t3.json setup actions to run without per-user import #5063 — run checked-in t3.json setup actions without per-user import

Current setup runner:

https://github.com/pingdotgg/t3code/blob/main/apps/server/src/project/ProjectSetupScriptRunner.ts

Contribution

• I would be open to helping implement this.

[gui-complypro]

+1 on this one.

For example I don't have the AGENTS.md (many different devs work in the project with their own preferences) committed in the repo, so I need to copy it over during the worktree setup - however it's too late and the agent doesn't have that in context.