agent-cli-worktree-safety

Agent-CLI Worktree Safety

Data-loss prevention for CLIs that create a git worktree, run an LLM orchestrator (claude-agent-sdk or similar) that writes files there, and then clean up with git worktree remove --force.

When to Use This Skill

The core failure mode

Three independent mistakes compound into silent data loss:

1. Driver phases write but never commit — "the outer orchestrator handles git state".
2. The outer orchestrator ends without committing — it stalls on an interactive tool call that cannot render (see Interactive tools in SDK subprocess mode below), or simply finishes.
3. The "has changes" check only counts commits (git log base..HEAD), so it reports nothing to preserve — and cleanup force-removes the worktree.

Net result: many files are written, the user is told "No changes were made", and the work is destroyed. No error, no traceback. That user-visible message is the diagnostic tell — if a run wrote files and reported no changes, check invariant 1 before anything else.

Required invariants

1. "Has changes" means commits OR a dirty tree

Any function deciding whether a worktree is worth preserving must return true when the working tree is dirty, even with no commits beyond base:

def worktree_has_changes(worktree_path, base_branch):
    commits = subprocess.run(
        ["git", "log", "--oneline", f"{base_branch}..HEAD"],
        cwd=worktree_path, capture_output=True, text=True,
    )
    if commits.stdout.strip():
        return True
    dirty = subprocess.run(
        ["git", "status", "--porcelain"],
        cwd=worktree_path, capture_output=True, text=True,
    )
    return bool(dirty.stdout.strip())