feat(worktree): add Git worktree support for isolated parallel sessions

Introduces a central Git worktree management system to enable isolated, parallel agent orchestration. This allows running multiple Gemini sessions on different branches within the same repository without file contention.

Key Features:
- Added 'WorktreeService' in @google/gemini-cli-core to manage creation, lifecycle, and cleanup of Git worktrees.
- Implemented smart cleanup logic that detects untracked files and new commits, automatically preserving worktrees with uncommitted work.
- Added '--worktree' (-w) flag to the CLI to launch sessions in fresh, isolated environments.
- Enhanced the session exit experience with detailed status messages and instructions for resuming work in preserved worktrees.

docs/cli/git-worktrees.md

@@ -0,0 +1,112 @@
+# Parallel sessions with Git worktrees
+
+When working on multiple tasks at once, you can use Git worktrees to give each
+Gemini session its own copy of the codebase. Git worktrees create separate
+working directories that each have their own files and branch while sharing the
+same repository history. This prevents changes in one session from colliding
+with another.
+
+Learn more about [session management](./session-management.md).
+
+> **Note:** This is a preview feature currently under active development. Your
+> feedback is invaluable as we refine this feature. If you have ideas,
+> suggestions, or encounter issues:
+>
+> - [Open an issue] on GitHub.
+> - Use the **/bug** command within Gemini CLI to file an issue.
+
+Learn more in the official Git worktree
+[documentation](https://git-scm.com/docs/git-worktree).
+
+## How to enable Git worktrees
+
+Git worktrees are an experimental feature. You must enable them in your settings
+using the `/settings` command or by manually editing your `settings.json` file.
+
+1.  Use the `/settings` command.
+2.  Search for and set **Enable Git Worktrees** to `true`.
+
+Alternatively, add the following to your `settings.json`:
+
+```json
+{
+  "experimental": {
+    "worktrees": true
+  }
+}
+```
+
+## How to use Git worktrees
+
+Use the `--worktree` (`-w`) flag to create an isolated worktree and start Gemini
+CLI in it.
+
+- **Start with a specific name:** The value you pass becomes both the directory
+  name (within `.gemini/worktrees/`) and the branch name.
+
+  ```bash
+  gemini --worktree feature-auth
+  ```
+
+- **Start with a random name:** If you omit the name, Gemini generates a random
+  one automatically (for example, `worktree-a1b2c3d4`).
+
+  ```bash
+  gemini --worktree
+  ```
+
+> **Note:** Remember to initialize your development environment in each new
+> worktree according to your project's setup. Depending on your stack, this
+> might include running dependency installation (`npm install`, `yarn`), setting
+> up virtual environments, or following your project's standard build process.
+
+## How to exit a worktree session
+
+When you exit a worktree session (using `/quit` or `Ctrl+C`), Gemini
+automatically determines whether to clean up or preserve the worktree based on
+the presence of changes.
+
+- **Automatic removal:** If the worktree is completely clean—meaning it has no
+  uncommitted changes and no new commits have been made—Gemini automatically
+  removes the worktree directory and deletes the temporary branch.
+- **Safe preservation:** If Gemini detects any changes, it leaves the worktree
+  intact so your work is not lost. Preservation occurs if:
+  - You have **uncommitted changes** (modified files, staged changes, or new
+    untracked files).
+  - You have made **new commits** on the worktree branch since the session
+    started.
+
+Gemini prioritizes a fast and safe exit: it **does not display an interactive
+prompt** to ask whether to keep the worktree. Instead, it ensures your work is
+safely preserved by default if any modifications are detected.
+
+## Resuming work in a worktree
+
+If a worktree was preserved because it contained changes, Gemini displays
+instructions on how to resume your work when you exit.
+
+To resume a session in a preserved worktree, navigate to the worktree directory
+and start Gemini CLI with the `--resume` flag:
+
+```bash
+cd .gemini/worktrees/feature-auth
+gemini --resume latest
+```
+
+## Managing worktrees manually
+
+For more control over worktree location and branch configuration, or to clean up
+a preserved worktree, you can use Git directly:
+
+- **Clean up a preserved worktree:**
+  ```bash
+  git worktree remove .gemini/worktrees/feature-auth --force
+  git branch -D worktree-feature-auth
+  ```
+- **Create a worktree manually:**
+  ```bash
+  git worktree add ../project-feature-a -b feature-a
+  cd ../project-feature-a && gemini
+  ```
+
+[Open an issue]: https://github.com/google-gemini/gemini-cli/issues