[Feature] Per-call `baseRef` on the Agent/Task tool (isolation:"worktree") to override the session-wide worktree.baseRef setting
Summary
Add an optional baseRef parameter to the Agent / Task tool invocation (the isolation: "worktree" dispatch), letting a single dispatch override the session-wide worktree.baseRef setting:
Agent({ isolation: "worktree", baseRef: "head" | "fresh", /* … */ })
Precedence: per-call baseRef → project/user worktree.baseRef setting → default (fresh).
Problem
worktree.baseRef (fresh | head) is a session/project-wide setting, but the correct base for a worktree depends on the individual dispatch, not the session:
- Dependent / stacked subagents need
head— an implementer for task N must see tasks 1…N-1 already committed on the current feature branch. - Independent parallel fan-out needs
fresh— each agent should branch from a clean default-branch base; otherwise every agent inherits the orchestrator's current feature branch, and each resulting PR diffs "dirty" against the default branch (unrelated commits show as scope creep).
A single global value can't express both. An orchestrator that runs stacked task-orchestration and independent fan-outs in the same session is forced to pick one. Today the only workarounds are:
- Flipping the global
worktree.baseRefsetting mid-session (racy, affects concurrent dispatches, and — per the setting's own semantics — may require a restart), or git checkout <default-branch>before an independent fan-out and back after.
Both are clumsy and error-prone for what is fundamentally a per-dispatch decision.
Proposed behavior
- Optional
baseReffield on the Agent/Task tool call, enum["fresh", "head"], matching the existing setting's values. - When present, it governs the base of that dispatch's worktree only; when absent, the existing
worktree.baseRefsetting (then thefreshdefault) applies. - Applies to
isolation: "worktree"dispatches. (Analogous handling forEnterWorktree/--worktreewould be consistent but the tool-call parameter is the primary ask.)
Why the existing setting isn't sufficient
The worktree.baseRef setting (added ~v2.1.133) solved whether worktrees branch from origin/<default> vs local HEAD, but only as a global toggle. The decision it controls is genuinely local to each dispatch — a mixed-workload session needs different bases for different concurrent agents, which a session-scoped toggle structurally cannot provide.
Related
- #23622 — "Support selecting base branch when creating git worktree." Related in spirit, but it's a vague, interactive/CLI-oriented request that predates the
worktree.baseRefsetting; it does not ask for a per-invocation parameter on the Agent/Task tool for programmatic dispatch, nor address per-concurrent-agent choice. This request is specifically the latter. - Builds directly on the existing
worktree.baseRef(fresh|head) setting — same values, per-call scope.