claude-code - 💡(How to fix) Fix Agent tool with isolation:"worktree" silently discards all file changes on cleanup [1 participants]

Summary

When the Agent tool is invoked with isolation: "worktree", it runs in a temporary git worktree. On cleanup, if the agent has not pushed or committed to a remote branch, all file changes are automatically discarded. This is not prominently documented and causes a silent data loss pattern.

Steps to reproduce

1. Invoke the Agent tool with isolation: "worktree" and ask the agent to edit or write files.
2. The agent runs, reports completion ("All files updated"), and the tool returns.
3. Inspect the original working tree — no changes are present.

Expected behavior (from docs)

The Agent tool documentation mentions that worktrees are "automatically cleaned up if the agent makes no changes" — but the behavior when the agent DOES make changes is not clearly explained. Users expect that file edits persist.

Actual behavior

File edits made inside the worktree do NOT persist to the original working tree unless:

• The agent pushes to a remote branch, OR
• The agent commits to the worktree branch which is then explicitly merged

Agents that only write files (without committing/pushing) lose all changes on worktree cleanup.

Proposed fix

1. Add a prominent warning in the Agent tool documentation for isolation: "worktree":

   Warning: File changes in a worktree agent do not automatically propagate to your working tree. Only committed+pushed changes survive cleanup.

2. Consider returning the list of changed files (or a diff) when the worktree is cleaned up, so the orchestrating agent can detect the data loss.

Workaround

Do not use isolation: "worktree" for implementation tasks where file persistence is required. Use it only for read-only research or exploration agents.

Environment

Claude Code (CLI), Agent tool with isolation: "worktree".