Edit code with diff review

Forge’s contract is that the agent never edits code silently. Every change lands as a diff card in chat. You decide which hunks apply.

What it looks like

Ask the agent to make a code change:

Add a debounce to the search input in src/components/SearchBar.tsx. 250ms.

Instead of writing the file directly, the agent emits a card with:

• The file path at the top.
• A one-line explanation of what’s changing.
• A commit message ready to use (Conventional Commits style).
• One or more hunks showing line ranges with red - lines for removals and green + lines for additions.
• A checkbox per hunk so you can pick exactly what to apply.

Review and apply

You can:

• Tick all hunks and approve if the whole proposal is right.
• Untick the hunks you don’t want and approve. Forge applies only the kept ones.
• Reject if the proposal is off-base. The agent gets the rejection signal and can try again with different reasoning.

When you approve, Forge:

1. Verifies the file’s current SHA-256 matches what the agent saw when it wrote the proposal. If they differ (you edited the file in another tool, or the agent worked from a stale read), the apply is refused with a clear “stale” message. Ask the agent to re-read and propose again.
2. Applies the kept hunks.
3. In a git repository, runs git add <file> followed by git commit -m "<the proposed message>". The commit gets a Forge-Applied: edit-proposal trailer so Forge can later identify it as agent-made.

Reverting

The Inspector’s Git tab shows recent commits. Forge-applied commits are marked with a small badge. The Revert last agent commit button only fires if the most recent commit has the Forge trailer; it refuses to revert your hand-authored work.

For deeper rollback, use git directly. Forge’s commits are normal git commits, not anything special.

Multi-file edits

A single proposal can target multiple files. Each file gets its own card with its own hunks and its own SHA-256 guard. Approving the proposal applies them as a single commit if you’re in git, so reverting one undoes them together.

What’s not here

Forge’s diff review currently covers code edits. It doesn’t yet cover:

• Renames (proposed as a delete + create today).
• Binary files (handled outside the proposal flow).
• Multi-step refactors that span many edits across many turns. Each turn’s edits land independently.

A richer multi-step refactor flow is on our roadmap.

Notes

• Diff cards work in any project, with or without git. Without git, Forge applies the changes but skips the auto-commit.
• The proposal block format is documented in Proposal block formats if you want to write tooling against it.
• Plan mode makes the agent emit diff cards exclusively. Switch to it when you want everything reviewed before any code lands.