[FEATURE] EnterWorktree should apply worktree.sparsePaths (parity with --worktree CLI flag)

Resolved 💬 2 comments Opened Mar 17, 2026 by mlarraz Closed Apr 15, 2026

Feature Description

The worktree.sparsePaths setting (introduced in v2.1.76) works correctly when creating worktrees via claude --worktree, but is silently ignored when the EnterWorktree tool creates worktrees mid-session. This means worktrees created by EnterWorktree (and by extension Agent(isolation: "worktree")) are always full checkouts, even when worktree.sparsePaths is configured.

Reproduction

  1. Configure worktree.sparsePaths in .claude/settings.local.json:
{
  "worktree": {
    "sparsePaths": ["packages/my-app", "shared/utils"]
  }
}
  1. Start a session with --worktree:
claude --worktree test-cli

Result: Sparse checkout applied — only listed directories are materialized. Works correctly.

  1. In a normal session, call EnterWorktree:
> create a worktree named test-tool

Result: Full checkout — all directories materialized, no core.sparseCheckout in git config. worktree.sparsePaths is ignored.

Observed behavior

| Creation method | sparsePaths applied? | Checkout size (30 GB monorepo) |
|----------------|----------------------|-------------------------------|
| claude --worktree | Yes | ~1 GB |
| EnterWorktree tool | No | ~11 GB |
| Agent(isolation: "worktree") | Untested (likely no) | — |

The worktree created by EnterWorktree has no sparse-checkout configuration at all:

git -C .claude/worktrees/test-tool config --list | grep sparse
# (empty)

Attempted workarounds

  • updatedInput via PreToolUse hook: sparsePaths is not a recognized parameter on EnterWorktree, so injecting it via hook output has no effect.
  • Writing to settings file from PreToolUse hook: EnterWorktree doesn't re-read settings during execution, so dynamically written values aren't picked up.
  • Pre-populating settings file before session: Settings are present and valid, but EnterWorktree simply doesn't read worktree.sparsePaths.

Expected behavior

EnterWorktree should read worktree.sparsePaths from settings and apply sparse checkout, identical to the --worktree CLI flag code path.

Impact

High for monorepo users. Without this, the only way to get sparse worktrees is --worktree at session startup. Mid-session worktrees (useful for parallel sub-tasks via Agent(isolation: "worktree")) always pay the full checkout cost, which in large monorepos means:

  • Minutes of wait time per worktree creation
  • Gigabytes of wasted disk space per worktree
  • Potential disk exhaustion when multiple agents run in parallel

Environment

  • Claude Code version: 2.1.76
  • Git version: 2.49.0
  • OS: macOS (Darwin 25.3.0, arm64)
  • Monorepo size: ~30 GB, 188 top-level directories

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗