[FEATURE] Hover on a changed line in VS Code's native git diff shows Claude's rationale for that change

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When Claude Code finishes a task, I review the result in the diff — VS Code's Source
Control view and the native diff editor — not in the chat transcript. The transcript
explains the changes in long prose that is detached from the lines it describes, and the
diff shows exactly what changed but never why. For every non-obvious hunk (a guard
added, an error value swapped, an ordering changed) I have to scroll back through the
conversation and reconstruct which turn produced it and what the reasoning was. That
context switch is the slowest and most error-prone part of reviewing agent output, and
it gets worse with task size: a 12-file change means dozens of round trips between the
diff and the scrollback.

The information I need already exists at edit time — Claude knows why it is making each
edit at the moment it makes it — but it is thrown away as unstructured chat text instead
of being attached to the lines it justifies.

Proposed Solution

Capture a short per-hunk rationale at edit time, and surface it on hover in VS Code's
native git diff.

1. When Claude Code performs an Edit/Write, the extension records a sidecar annotation

for the affected range: {file, range, contentHash, rationale, turnRef}. The
rationale comes from the authoring context — the conversation turn and tool call that
produced the edit — not from a second model pass over the diff afterwards.

1. The VS Code extension registers a hover provider for changed lines. Hovering a

changed line in the native git diff editor (Source Control working-tree diff,
inline diff from the gutter change indicators, or a modified line in the regular
editor) pops up the rationale, one to three sentences, with a link back to the
conversation turn that made the change.

1. Annotations re-anchor by content hash as later edits shift lines, are marked stale

when the user hand-edits the line, and live until the change is committed.

The native git diff part is the point: review happens in the SCM view after (or during)
the session, on the working tree, across everything the task touched — not only inside
Claude Code's own per-edit diff panel.

Mockup:

+----------------------------------------+
| src/gateway/health.go (Working Tree)   |
+----------------------------------------+
|  41   if cfg == nil {                  |
| -42       return nil                   |
| +42       return ErrMissingConfig      |  (hover)
|  43   }                                |     |
+----------------------------------------+     |
                                               +-----------------------------+
                                               | Claude: why this change     |
                                               | nil reads as "healthy" to   |
                                               | callers; the new Run()      |
                                               | probe needs a distinct      |
                                               | error to fire the alert.    |
                                               | [view turn 14]              |
                                               +-----------------------------+

Alternative Solutions

• Reading the chat explanation — this is the workflow the feature replaces; the

prose is low-signal and not anchored to lines.

• explain-changes-mcp (community MCP + extension) — renders an annotated diff in a

webview panel. It is post-hoc self-review reconstructed from the diff, in a separate
panel rather than the native diff, and without hover or a link to the authoring turn.

• GitLens line hover — shows the commit message, so it only works after commit, says

nothing per line, and carries no agent context for working-tree changes.

• DIY: instruct Claude to append annotations to a JSON file on every edit and render

them with a small custom hover extension. This works but capture depends entirely on
model discipline, and the reliable mapping from tool call to hunk to conversation turn
exists only inside Claude Code itself — which is why this belongs in the product.

Priority

High - Significant impact on productivity

Feature Category

Developer tools/SDK

Use Case Example

1. I ask Claude Code to implement a health-check feature; it edits 12 files.
2. I open the Source Control view and review the working-tree diff file by file.
3. In health.go line 42, return nil became return ErrMissingConfig. The diff alone

does not tell me whether this is a drive-by refactor or load-bearing.

1. I hover the line. The popup says: "nil reads as 'healthy' to callers; the new Run()

probe needs a distinct error to fire the alert." with a link to turn 14.

1. I either accept the hunk or click through to the turn to challenge the reasoning —

without leaving the diff or scrolling the transcript once.

Additional Context

Related open issues, all adjacent, none of them this request:

• #44787 — review mode with inline comments: the user writes comments on Claude's

changes; here Claude's own authoring rationale is attached to lines automatically.

• #13720 — per-hunk explanation during an interactive review loop: explanation is

generated during a review pass, not captured at edit time, and lives in the chat flow
rather than on hover in the native diff.

• #31395 / #21447 — inline hunk accept/discard UI: approval mechanics, no rationale.

The differentiator in one sentence: *the explanation comes from the authoring context —
the turn and tool call that produced the edit, captured at write time — and is surfaced
where review actually happens, on hover in VS Code's native git diff.*

Technical sketch: the extension already knows the file and range of every Edit/Write and
the turn that issued it, so capture is a cheap side effect of the existing edit pipeline;
rendering is a standard HoverProvider over diff-editor and file URIs; content-hash
re-anchoring handles line drift; a stale marker handles user edits on top.