[Feature] Per-call `baseRef` on the Agent/Task tool (isolation:"worktree") to override the session-wide worktree.baseRef setting

Open 💬 0 comments Opened Jul 4, 2026 by mikehenson

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:

  1. Flipping the global worktree.baseRef setting mid-session (racy, affects concurrent dispatches, and — per the setting's own semantics — may require a restart), or
  2. 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 baseRef field 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.baseRef setting (then the fresh default) applies.
  • Applies to isolation: "worktree" dispatches. (Analogous handling for EnterWorktree/--worktree would 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.baseRef setting; 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.

View original on GitHub ↗