Feature: Let EnterWorktree create the new branch from a caller-specified base ref

Feature: Let EnterWorktree create the new branch from a caller-specified base ref

Summary

EnterWorktree currently creates the new branch from the main repo's local HEAD (after the recent fix that replaced origin/<default-branch>). That's a real improvement — unpushed commits on the current branch no longer get dropped — but it still ties the new worktree's base to wherever the calling checkout happens to sit.

It would be great if EnterWorktree accepted an optional base (or startPoint) argument so the caller could pin the new branch to a specific ref like origin/dev, origin/main, or any other commit-ish, regardless of the main repo's current HEAD.

Why local HEAD isn't enough for everyone

The implicit assumption behind "branch off local HEAD" is that the main repo's checkout is sitting on the branch you'd want to fork from (typically main). For a lot of teams that's true. For others, including ours, it isn't — and we end up unable to use EnterWorktree at all from automation, even though it would otherwise be a perfect fit.

It's not unusual for a repo to have a stable release branch and a separate active development branch, where day-to-day work happens off the dev branch and the stable branch is reserved for releases / hotfixes. In that setup:

• The GitHub default branch is the stable one (e.g. main) — that's what PRs from external contributors target by convention, what gets tagged for releases, etc.
• All internal feature branches are cut from and merged back into the dev branch (e.g. dev).
• A developer running a "start new task" workflow is very often not sitting on the dev branch when they invoke it — they're mid-task on some other feature branch. We deliberately don't want to disturb that checkout to start a new task.

In that world, "branch from local HEAD" can mean "branch from a half-finished feature branch," which is exactly the wrong base.

Concrete use case (ours)

We have a project-side skill that orchestrates "start work on ticket X." It does roughly:

1. git fetch origin
2. git worktree add ../<branch> -b <branch> origin/dev
3. Adopt the new worktree via EnterWorktree({ path: "../<branch>" })

Step 2 is only there because we need an explicit base. We can't let EnterWorktree create the branch itself, because:

• Pre-fix, it would have based the branch on origin/main (our stable branch) — wrong base, would have produced PRs full of unrelated diff.
• Post-fix, it bases the branch on local HEAD, which is whatever the developer happened to be on when they kicked off the workflow — also wrong, and unpredictable from automation's standpoint.

What we actually want is "branch off origin/dev, every time, regardless of where my checkout currently is." That requirement is independent of the main repo's working tree, and we'd rather express it as a parameter than work around it with a manual git worktree add we then adopt.

Proposed shape

Add an optional base parameter to EnterWorktree that accepts any commit-ish git understands (origin/dev, main, a tag, a SHA, etc.):

EnterWorktree({
  branch: "CU-12345_fix-thing",
  base: "origin/dev",
})

Behavior:

• If base is omitted: current behavior (create from local HEAD). No breakage for anyone happy with the default.
• If base is provided: resolve it the same way git worktree add <path> -b <branch> <base> would. If it's unresolvable, surface the git error rather than silently falling back.
• If base resolves to a remote-tracking ref, no implicit git fetch — leave that to the caller, same as git worktree add.
• The path and existing-worktree adoption paths shouldn't change.

A startPoint alias could be nice for parity with git branch/git worktree add terminology, but a single name is fine.

Why this beats workarounds

The "shell out to git worktree add first, then adopt with path" pattern works (it's what we do today), but it has real downsides for a tool-driven flow:

• Two steps instead of one — more places for the automation to fail partway and leave orphaned branches/worktrees behind.
• The adoption step can't validate that the worktree was actually created from the base we expected; it just trusts the path.
• Skills written by other teams hit the same gotcha and rediscover the workaround independently. A first-class parameter would document the contract.

Related

• #27134 — the recent fix from origin/<default> to local HEAD. This proposal is the natural next step: let the caller specify the base explicitly when local HEAD isn't the right answer.
• #31969 — overlapping space (worktree ergonomics) but different scope.

Happy to iterate on the parameter name / shape if there's a preferred convention.