Agents Window: Make Git/worktree context and actions understandable end to end

@eli-w-king is already working on this.

Since Sep 17, 2026.

_Last refreshed: September 17, 2026_

## Summary

Git and worktree isolation are central to the Agents Window, but the relevant state and actions are spread across the new-chat page, Sessions list, terminal, Changes view, and session lifecycle menus.

As a result, it is difficult to answer a few basic questions with confidence:

- Which repository, worktree, and branch is this session using?
- Where will a new session start?
- Will this action commit locally, push/sync, merge, or create a pull request?
- What commit message will be used?
- Which worktrees has the Agents Window created on my machine, and when will they be cleaned up?

There are several open issues covering individual parts of this experience. This issue is intended to summarize the cross-surface problem and identify opportunities for a more coherent end-to-end workflow.

## Recent progress since September 3

Several relevant improvements landed during the past two weeks:

- #335431 added a unified, configurable **Create PR** form for Agent Host sessions. It opens while generated PR details are prepared, preserves edits, exposes draft/merge choices, and lets users either create the PR directly or send the request to the agent.
- #334341 added opt-in Preview settings to automatically mark inactive sessions with merged PRs as Done and later permanently delete eligible archived sessions. Marking a session as Done follows the normal archive lifecycle, which removes its managed worktree; restoring the session recreates the worktree.
- #335360 made the merged-PR **Mark as Done** nudge explain that the session is hidden rather than deleted and that its removed worktree is recreated when the session is restored.
- #335851 restored manual cleanup for dirty worktrees: explicitly marking a session as Done first commits its uncommitted changes and then removes the worktree, while a commit failure retains the worktree.
- #335722 added `sessions.useWorktree`, which controls whether **New Worktree** is selected for a user's first session.
- #335077 made the `create_session` tool honor an explicit request to create or avoid a new worktree.

These changes improve the individual actions, but they also produced useful follow-up reports that reinforce the broader coherence problem:

- The Create PR flow does not always surface the resulting PR link (#335773), PR links open inconsistently in-product versus in the browser (#335778), the action is tied to a specific session rather than project changes (#335764), and an edited generated description can be lost when the form is dismissed (#335881).
- Commit and Sync actions still lack an explicit completion/result confirmation (#335316).
- Failed worktree creation can fall back to the original checkout while the session remains active (#335776, #336082), the agent can incorrectly claim isolation succeeded (#335779), or the UI can remain stuck at **Worktree · Creating...** without identifying the actual directory or branch (#336353).
- Automatic Mark as Done and cleanup now exist as opt-in settings, but their operation remains mostly background state. Recent follow-ups covered stale eligibility (#335612, fixed), worktrees with uncommitted changes (#335840, fixed by #335851), and repeated expensive evaluation of retained sessions (#335879).

## Current experience

### Selecting and understanding the working location

- Selecting a specific existing worktree from the new-chat page is difficult and disconnected from the rest of the session-creation flow. Existing worktrees do not feel like first-class starting locations.
- The repository/worktree choice is not prominent enough before sending the first prompt, and it is easy to lose track of the choice after the session starts.
- Worktree and branch information is available in the rich hover for a session in the Sessions list, but this is important orientation information rather than secondary hover detail.
- The terminal currently provides one of the best orientation cues. When multiple sessions/windows are open, selecting a session restores the correct terminal, and the terminal path immediately helps confirm the current location. The chat/session surface should reuse this strength, perhaps by showing repository, worktree, and branch in the chat title bar.
- Generated worktree and branch names can be hard to associate with the task or parent repository, making the Window menu, session list, and manual cleanup difficult to scan.

Related: #311028, #299627, #299713, #327945, #312729, #325817, #309410

### Starting from a worktree

- Worktrees are not listed or grouped clearly as places where a new session can start.
- Starting a fresh chat in the same worktree is not an obvious flow.
- Folder/worktree selection state can be confusing or appear inconsistent.
- The location and naming policy for automatically created worktrees is not visible or configurable enough.
- Agent-created independent sessions can now explicitly request a worktree, but choosing the base branch is not yet supported.

Related: #300473, #309027, #320811, #293884, #335777

### Commit, sync, and pull request actions

- The top-right primary action and its dropdown do not consistently make the full effect of an operation clear. Depending on the session/provider and available action, a commit path may also sync/push, while a local-only commit can leave the next step unclear.
- The product has concepts such as **Commit Changes**, **Commit and Sync Changes**, **Sync Changes**, **Merge Changes**, and **Create PR**, but the action hierarchy can make these feel interchangeable even though they cross different local and remote boundaries.
- The Commit option can be replaced by Create PR as the primary action without Commit remaining available in the dropdown. Even if Create PR performs the necessary commit automatically, the lower-level operation should remain understandable and discoverable.
- Worktree sessions and in-place workspace sessions can offer different ways to integrate otherwise similar local changes, making the end-of-task workflow feel inconsistent.
- Errors from Git actions are not always surfaced where the action was initiated, which further reduces confidence in whether an operation completed.
- Successful Commit and Sync actions also need an explicit result: the current action can disappear without confirming the commit, remote state, or next step.
- The new Create PR form improves configuration and editing, but the resulting PR and its opening behavior are not yet presented consistently across the form, chat, header, and session hover.
- When changes appear to be in the wrong worktree, correcting the situation through discard or cleanup feels high-risk because the active checkout and recovery path are not prominent enough.

Related: #305870, #313548, #315363, #335316, #335773, #335764, #335778, #335881

### Commit message transparency

- There is no preview of the commit message before committing.
- The generated commit message cannot be reliably edited or overridden.
- After the action completes, there is limited visibility into the resulting commit and whether it remained local or was pushed.

Related: #306948, #315962

### Worktree lifecycle and cleanup

- The Agents Window creates worktrees on the user's machine, but there is no central visibility into which worktrees it manages, where they are located, or their cleanup state.
- **Mark as Done** now removes a managed worktree and restoring the session recreates it; manual cleanup first commits uncommitted changes and retains the worktree if that commit fails. This behavior should remain visible at the point of action and in the session's lifecycle status, not only in onboarding text.
- Opt-in automatic Mark as Done/delete settings now exist for inactive sessions with merged PRs, but users still cannot inspect the pending decision, retained worktree, next evaluation, or cleanup result in one place.
- Cleanup may fail without a sufficiently visible or actionable recovery path.
- Deleting a session and archiving a session do not necessarily have the same worktree behavior.
- Restoring an archived session after its worktree was removed can leave the user without a clear way to continue.
- Worktree-created setup tasks can provision external resources, but there is no corresponding awaited cleanup lifecycle before the worktree is removed.

Related: #332442, #327261, #309417, #324248, #329776, #335879

### Isolation failure and truthfulness

- Worktree isolation should be a guarantee, not a best-effort hint. If creation fails, silently continuing in the original checkout can put the user's active work at risk.
- The session, agent transcript, hover, and terminal must agree on whether a worktree exists and which directory/branch is active.
- A failed or still-pending worktree should block mutating work until the user deliberately chooses a safe recovery path.

Related: #335776, #335779, #336082, #336353

## Why this matters

These are not only discoverability issues. Together they affect trust and safety:

- Users may discard, merge, or delete changes while unsure which checkout is active.
- Users may unexpectedly cross a remote boundary by pushing changes.
- Users cannot review or control the Git history that the workflow creates.
- Stale worktrees and related resources can accumulate on disk.
- Users working across several parallel sessions have weak persistent cues for reconnecting a task, session, branch, worktree, terminal, and pull request.

This is closely related to the broader parallel-work problems described in #322931 and #311858.

## Opportunities

### 1. Persistent session location identity

Show the session's location as persistent, glanceable context:

- parent repository/project;
- folder or worktree;
- current branch;
- local/remote execution location.

This could live in the chat/session title bar and use the same terminology across the new-chat page, Sessions list, terminal, Changes view, and window title. Hover can provide additional detail, but should not be the only place that identifies the worktree.

### 2. A first-class worktree picker

- Present existing worktrees as explicit starting locations.
- Group worktrees under their parent repository and label them with their branch.
- Distinguish **use this existing worktree** from **create a new isolated worktree**.
- Allow the base branch to be selected when creating a new worktree.
- Keep the selected location visible before the first prompt and after the session starts.
- Offer an easy way to start another chat/session in the current worktree.

### 3. Explicit Git action semantics

- Name primary actions by their complete effect: **Commit**, **Commit and Sync**, **Merge**, **Create PR**, etc.
- Make it visually clear when an action will push or otherwise cross a remote boundary.
- Keep lower-level actions available in the dropdown when a higher-level action becomes primary.
- Before execution, summarize the target branch/repository and the operations that will occur.
- After execution, show exactly what happened, including the resulting commit/PR link and the recommended next step.

### 4. Commit transparency and control

- Preview the generated commit message.
- Allow it to be edited before committing.
- Show the resulting commit SHA/message and whether it is local or pushed.
- Allow users to choose a local-only commit even when Create PR is available.

### 5. Visible worktree lifecycle

Provide a management surface or session details section that shows:

- worktrees created or managed by the Agents Window;
- disk location, parent repository, branch, and associated session;
- whether the worktree is active, archived, missing, pending cleanup, or failed cleanup;
- what will happen on archive, delete, restore, and permanent deletion;
- recovery or manual cleanup actions when automation fails.
- automatic archive/delete eligibility, retention timing, and the reason a worktree was retained.
- whether cleanup was initiated by an explicit **Mark as Done** action or by a previously configured automatic-cleanup setting.

### 6. Safety and recovery

- Make the active checkout and target branch unmistakable before discard, merge, delete, or cleanup operations.
- Explain whether recovery is available through checkpoints, commits, branches, session history, or the worktree itself.
- Preserve or clearly communicate important local state when creating a worktree; see #315773.
- Keep branch/worktree/PR identity synchronized; see #316465 and #326925.

## Related issues

This issue is not intended to replace the narrower reports:

- **Orientation and identity:** #311028, #299627, #299713, #327945, #312729, #309410
- **Worktree selection and creation:** #300473, #309027, #320811, #293884, #325817, #335777
- **Isolation failures:** #335776, #335779, #336082, #336353
- **Commit/PR workflow:** #305870, #313548, #315363, #335316, #335773, #335764, #335778, #335881
- **Commit messages:** #306948, #315962
- **Lifecycle and cleanup:** #332442, #327261, #309417, #324248, #329776, #335879
- **Correctness and local context:** #315773, #316465, #326925
- **Broader parallel workflows:** #322931, #311858

The opportunity is to design these pieces as one coherent Git/worktree journey rather than solving each surface independently.