docs(rfd): HITL Editing — Interactive File Write Feedback

[Luminger]

Summary

This adds an RFD proposing HITL (Human-in-the-Loop) editing for ACP's fs/write_text_file path.

The proposal extends WriteTextFileResponse with optional fields that allow clients to report user modifications and feedback back to the agent when the user edits a proposed file change before accepting it. This closes the feedback loop that is currently missing: the agent proposes a change, the user tweaks it, and the agent learns what was changed — all within a single interaction.

The proposal:

• Introduces a ContentDiff type — a reusable, format-discriminated diff primitive (unified or full) that ACP currently lacks
• Adds an agentCapabilities.fs.hitlEditing capability for agents to advertise support
• Extends WriteTextFileResponse with a discriminated action field (accept | reject | cancel) following the same pattern as ElicitationAction and RequestPermissionOutcome
• On accept, includes an optional userModification object (diff as ContentDiff + finalContent) when the user edited the proposal
• Adds an optional feedback string for user comments on both accept and reject paths
• Addresses users who prefer the existing workflow — HITL editing is opt-in, and clients may offer settings to fall back to a read-only diff view or auto-approve
• Is fully backward compatible — existing clients continue returning null or {}

Note on ContentDiff: The ContentDiff type is presented as a firm part of the proposal, but we recognize it could be considered a separate concern. If the maintainers prefer to keep userModification.diff as a plain string and address the general-purpose diff type separately, the ContentDiff type can be dropped without affecting the rest of the proposal. The name ContentDiff was chosen to avoid a naming clash with the existing Diff type in ToolCallContent, and to signal that the type is not inherently limited to plaintext — future format variants could support binary patches or other content types.

Motivation

Agentic coding tools today are stuck in a binary accept/reject model for file writes. Even when the agent's proposal is close to the desired change, the user can only accept or reject, which can lead to frustrating multi-turn ping-pong before converging on the desired result. Worse, some editors already allow users to edit the proposed diff before accepting, but the agent is never informed about these edits, causing it to work from an outdated understanding of the file.

The proposed pattern was pioneered by the Cline family of harnesses (Cline and Roo Code) and has proven effective in practice. This RFD introduces this pattern to the ACP ecosystem.

Prior Art

This pattern is already implemented and battle-tested in the Cline family of harnesses:

Roo Code

• DiffViewProvider.saveChanges() — Core HITL logic: compares the agent's proposed content to the user's (potentially modified) content in the diff editor, generates a unified diff via createPrettyPatch(), and returns { userEdits, finalContent }.
• DiffViewProvider.pushToolWriteResult() — Formats the structured JSON response sent back to the agent, including user_edits (the diff) and problems (new diagnostics). Also sends a user_feedback_diff message to the UI.

Cline

• DiffViewProvider.saveChanges() — Same core pattern: detects user modifications, generates a unified diff, returns { userEdits, finalContent }.
• WriteToFileToolHandler — Consumes the saveChanges() result and sends user_feedback_diff to the UI when the user made edits.
• formatResponse.fileEditWithUserChanges() — Formats the prose response sent to the model: includes the user's diff, the final file content, and instructions to use the updated content as the new baseline.

Both implementations share the same core mechanism: diff view as a gate → user edit detection → unified diff generation → feedback to the agent. The key difference is that Roo Code returns structured JSON while Cline uses prose.

Related Discussions & PRs

• Allow client to edit tool calls during permission requests #221 — @WhiskeyJack96 raised the exact same problem in Nov 2025: users wanting to edit tool call proposals before approving, with the agent being informed of the changes. That discussion received no replies and no RFD was filed. This proposal is the first formal solution.

• docs(rfd): client-owned fs/apply_patch #808 — We are strongly in favor of fs/apply_patch and see it as the other half of the same story: fs/apply_patch addresses the input format (how agents send structured edits), while HITL editing addresses the output (how clients report user modifications back). We would like to see both proposals align and integrate — specifically, fs/apply_patch should adopt the same outcome-based action field and userModification feedback in its response, so that agents get a consistent HITL experience regardless of whether they write files via fs/write_text_file or fs/apply_patch.

• Extend Diff type #176 / docs(rfd): Indicate deletes in diffs #441 — The existing ACP Diff type (used in ToolCallContent) carries oldText/newText full-content pairs for displaying agent-proposed changes in the client UI. Rather than reusing it or introducing a one-off string field, we designed a new ContentDiff type with a format discriminator (unified for compact patches, full for before/after content). This addresses @benbrandt's comment on docs(rfd): Indicate deletes in diffs #441 — "let's turn this into the long-awaited new version of diff that supports more info" — by providing a general-purpose diff primitive that could also serve the existing ToolCallContent.Diff and any future extensions. That said, if the maintainers prefer to address the general diff type separately, ContentDiff can be dropped from this proposal and userModification.diff can remain a plain string.