Proposal: Reviewable Agent Edits with Native Track Changes and MCP Approval Feedback

[Augusto-Zolet]

Hey Keith! I'm back to the idea of letting people approve or reject agent edits. I've been organizing my thoughts and running experiments, and the trickier parts actually work, including the wait-for-approval flow over MCP.

What I'm going for

The agent shouldn't silently change the document. Every edit the agent makes should be something the user can look at and accept or reject, seeing the old and the new before deciding.

The things I treat as non-negotiable for this to actually be useful:

• The user can accept or reject each change.
• Reject puts the text back exactly as it was.
• Accept keeps it.
• When deciding, the user sees both the old and the new version, not just the end result.
• And — this one's subtle — the agent has to know what the user decided. If it assumes an edit stuck and the user actually rejected it, its next step ("find the sentence I just wrote") could break for example.

How I think we do it

Native Track Changes, like you suggested. There's a setting that, when on, makes the agent's edits get recorded as tracked changes, so the user reviews them with the accept/reject UI they already know, inline. Mechanically it just turns RecordChanges on around the agent's edit and restores your previous setting afterward, so your own typing isn't affected. I wired it into the places the agent actually edits: the main edit tool, the edit-selection rewrite, and the script/vision result insertion.

(If you'd already turned Track Changes on yourself, the agent leaves it on, it doesn't flip it off and on behind your back. The only spot it briefly toggles is the streaming rewrite: it records with tracking off and then re-applies the result as one clean change, so you don't get a redline per typed word — but you end up exactly where you started, tracking-wise.)

The hard parts, and how I'm thinking about them

1. Paragraph styles don't track. LibreOffice records text and character formatting (bold, color, size…) as tracked changes, but not a paragraph-style change (turning something into Heading or Caption). I tried faking it — delete the text and re-insert it so the change rides a real tracked edit — but on reject the text comes back and the new style stays, which is worse than not tracking at all (silently wrong). So for now: style changes apply directly, and the agent just tells the user it changed a style (the text edits in the same turn are still reviewable). I don't have a clean way to make style changes truly reviewable yet, so I'm setting that aside for now.

2. The agent knowing what you decided — and it works over MCP. The review itself is native LibreOffice, so accepting/rejecting is identical whether the agent runs in the in-app chat or over MCP. The part I wanted to nail is the agent learning the outcome. The flow: the agent makes one call that edits the document and then doesn't return — it waits while you accept/reject in LibreOffice, and only once you've gone through its changes does the call hand back, telling the agent what you kept. That fits MCP fine — one request, one response; the response just comes back after you've reviewed.

   I wired up a quick version and tested it over MCP, and it's not hypothetical: the agent's write call stayed open until I'd reviewed — other tool calls kept working normally in the meantime (the server didn't freeze) — and it came back with a per-change result. When I accepted two of the changes and rejected one, the response correctly labeled each one accepted or rejected.

   Two things I had to work out:

   • How the call knows you're done: it watches for none of the agent's changes being left unreviewed — i.e. you've accepted or rejected all of them. No extra button.
   • Telling accept from reject, per change: a single tool call can make several changes (a multi-block write, a full rewrite, a replace-all), so what the agent really wants back is its list of changes, each marked accepted or rejected — even if you accepted some and rejected others. The catch is that a tracked change disappears whether you accept OR reject it, so you can't read the result off the redline afterward. What works (and what the test above used): when the agent makes its changes, tag and anchor each one and record its original + proposed text up front; after you've reviewed, re-read each anchored spot and compare — matches the proposed → accepted, matches the original → rejected. I'd anchor each change with a bookmark so it survives the positions shifting as you resolve the others.

   One gotcha worth flagging for the implementati** Tracked changes live inside the document, so they only survive a close/reopen if the file is saved. Since the whole point is reviewing the agent's edits — maybe not right this second — I'd have it save automatically after the agent's changes when review mode is on, so they're waiting for you the next time you open the file. It's safe: they stay tracked changes, so you can still accept or reject them after reopening — saving doesn't commit them. (One open case: a brand-new document that's never been saved has no filename yet — there we'd either prompt for a location or hold off on the auto-save until it's been saved once.)on: to hold a call open like this, the tool has to run on a background thread — and since LibreOffice's API isn't thread-safe, any actual document edits inside it have to be handed back to the main thread. The framework already enforces this (it refuses a background tool that touches the document directly), and a couple of existing long-running tools already follow the pattern, so it's a known shape — just something to get right.

   The one practical limit is a very long wait vs. the client's timeout: if you walk away mid-review, we don't want the call to just hang. So after a sensible max-wait it returns to the agent "you haven't reviewed these yet," and the agent can then nudge you to accept or reject the changes before it carries on — I tested this too: with nothing reviewed, it came back at the timeout asking the user to go review. (A keepalive could stretch the wait, but the simple timeout-and-nudge is probably enough.)

3. "Extend selection" writes gradually. This is the one feature that streams the AI's text into the doc bit by bit, so recording it naively would give you a redline per chunk. I experimented with it and it works cleanly: stream it live with tracking off (you still see it appear), then at the end record just the appended text as a single tracked insertion. In my test that produced exactly one change — reject restored the original, accept kept it. Same shape as the rewrite path, just needs wiring in.

4. Attribution. To make the agent's changes show up as the agent's (not yours), I'd briefly set the author name to "WriterAgent" during the edit and restore it after. It works, but it's a global setting for that moment, so I'd scope it tightly — set it, edit, put it back. If that feels too invasive, the fallback is tagging each change with a comment instead of renaming the author — your call.

5. Persistence — saving so you can review later. Tracked changes live inside the document, so they only survive a close/reopen if the file is saved. Since the whole point is reviewing the agent's edits — maybe not right this second — I'd have it save automatically after the agent's changes when review mode is on, so they're waiting for you the next time you open the file. It's safe: they stay tracked changes, so you can still accept or reject them after reopening — saving doesn't commit them. (One open case: a brand-new document that's never been saved has no filename yet — there we'd either prompt for a location or hold off on the auto-save until it's been saved once.)

What do you think? Any suggestions?

[KeithCu]

Hi!

This is a complicated feature but I agree it is interesting and worth doing, in spite of being a pain. Here's my notes:

1. Centralize — one module, one session type
   Avoid sprinkling RecordChanges / author toggles across apply_document_content, selection.py, script insert paths, etc.
   Add something like plugin/writer/edit_review.py with a single context manager:
   with EditReviewSession(doc, ctx, enabled=config) as session:
   session.record_mutation(apply_fn) # returns ChangeRecord list
   outcomes = session.wait_for_review(timeout=...) # polls on caller thread
   All entry points call this wrapper. Keeps restore-on-exception, bookmark cleanup, and author scoping in one place.
2. Tag agent changes — or “done” never fires
   Completion must not be “zero redlines in document.” Filter to this session only:
   • Set RedlineComment to a session token (e.g. wa-review:) when recording, or
   • Briefly set author to WriterAgent and filter RedlineAuthor + session id
   Otherwise: user’s pre-existing redlines, grammar suggestions, or manual edits while waiting will block or confuse completion.
   Use bookmark names wa_review (distinct from heading mcp* in BookmarkService) and always remove them in finally (success, timeout, error).
3. Fix the “review mode but tracking was off” gap
   Today WriterStreamedRewriteSession.finish() only collapses to a single redline when was_recording=True. Review mode must force temporary RecordChanges=True even when the user didn’t have tracking on — same for apply_document_content and extend-selection finish.
   Extend the session helper rather than duplicating logic in three places.
4. Sidebar chat: reuse web-research infrastructure, not its chrome
   mirror web search HITL wiring, not the Accept/Change/Reject buttons (those are pre-action query approval; edit review is post-action in the document).
   Reuse:
   • Config toggle pattern (chatbot.prompt_for_web_research → new key e.g. writer.require_edit_review)
   • is_async() = True on mutating tools when review enabled (same as WebResearchTool) so the LLM worker thread can block without freezing the drain loop
   • threading.Event + queue handoff pattern from tool_loop.py if you need main-thread UI hooks
   • status_callback → sidebar status: “Review tracked changes in the document…”
   Do not repurpose Send→Accept for per-redline review; native LO UI stays the review surface.
   Poll loop on the background worker:
   while not done:
   done, outcomes = execute_on_main_thread(check_session, timeout=...)
   time.sleep(0.3) # or stop_checker-aware
   Main thread stays free for accept/reject clicks (same reason MCP works).
5. Comparison edge cases — add a third outcome
   Compare anchored text using get_string_without_tracked_deletions (already used for edit-selection prompts):
   Current text Result
   equals proposed accepted
   equals original rejected
   else modified (user edited during review)
   Return modified explicitly so the agent doesn’t assume accept/reject.
6. Persistence — let LibreOffice handle save (no auto-save)
   Tracked changes live in the document model like any other edit. Review mode does not need special handling.
7. Show markup automatically
   On session start, dispatch .uno:ShowTrackedChanges (see TrackChangesShow) so users actually see redlines — easy to miss if markup was hidden.
8. Attribution — Try the global rename, as long as we have the LO thread, no one else can be doing anything so no one else will notice when we set it back and all other calls will wait. It should be fine as long as we don't do anything async.
9. HTML / multi-block writes
   apply_document_content import path can produce multiple redlines per logical edit. Two acceptable v1 strategies (pick one, don’t hybrid):
   • A (simpler agent model): one ChangeRecord per tool call (whole operation), one anchor spanning affected range — agent sees one accept/reject outcome for the batch
   • B (finer control): one anchor per search/replace match or content block — richer JSON, more bookmarks to maintain
   Recommend A for v1 unless you already tested multi-anchor reliably on HTML imports.
10. Scope and non-goals (keep code small)
    • Writer only for v1 (Calc has RecordChanges but different review UX)
    • Style-only mutations: apply directly + style_unreviewed: true in tool JSON + prompt line in constants.py
    • Don’t wrap WriterCompoundUndo and Track Changes in conflicting ways — review session owns the undo story for that mutation; compound undo stays for streaming visibility only

Standard tool response shape
Keep one schema everywhere (chat + MCP):
{
"status": "ok",
"review": {
"complete": true,
"timed_out": false,
"changes": [
{
"id": "wa-review:abc",
"accepted": true,
"original_preview": "...",
"proposed_preview": "..."
}
]
}
}
On timeout: "complete": false, "timed_out": true, list still includes pending entries. Agent system prompt: treat complete: false as “user may still have redlines — don’t assume text state.”

MCP vs sidebar — same core, two shells
Surface Shell
MCP Mark wrapped tools long_running = True; body calls shared EditReviewSession.wait_for_review() on HTTP thread
Sidebar When review enabled, mutation tools is_async() = True; same wait helper; status_callback for UX
MCP client timeout Document max wait in Settings; return partial review JSON before client 504

One thing that's tricky about making it an optional feature is you need to handle it being turned on and off at any time. Please make sure to handle that case and doing something reasonable. Will need to keep track of whether track changes was turned on by the user.

Okay if that sounds good, go for it, make a PR and I'll review!

Regards,

-Keith

[Augusto-Zolet]

Hi Keith! Sorry for going quiet this week, barely had any free time. I implemented the feature following your advices, tested everything, and I think it reached a nice maturity. Here's where it landed.

Your notes, point by point

• One module, one session type — done, exactly the shape you sketched: plugin/writer/edit_review.py with EditReviewSession; every entry point (the main edit tool, the edit-selection rewrite, the script/vision result insertions) goes through it. Restore-on-exception, bookmark cleanup and author scoping all live in that one place.

• Session tokens — every redline an edit creates gets a RedlineComment token (wa-review:<session>:<n>), and "done" means "no redline carrying this session's token is left" — pre-existing redlines, or anything the user does while it waits, never block completion. Anchors are wa_review_* bookmarks (distinct from the _mcp_* heading ones), and they're removed however the session ends: completed, timed out, aborted, or the edit itself raising halfway.

• The "tracking was off" gap — closed. Review mode forces recording on every path, including the streamed extend-selection finish, and what gets restored afterwards is whatever the user's RecordChanges state was before.

• Sidebar wiring — as you suggested: writer.require_edit_review config key, the tool turns is_async() on when review is enabled so the LLM worker thread blocks without freezing the drain loop, and status_callback shows "Review the agent's changes in the document…" while it waits. MCP marks the same tool long_running and blocks on the HTTP thread. Both shells run the same wait_for_review, with every document touch inside the poll marshalled to the main thread — which stays free for the accept/reject clicks. The max wait is a setting (writer.edit_review_timeout, default 900s, 0 disables waiting). Validated live in the in-app sidebar chat (not just over MCP): the chat tool loop blocked on the edit, the change appeared as a tracked redline, and once I accepted it inline the call returned {"complete": true, "changes": [{"outcome": "accepted", ...}]} straight back into the chat. One caveat worth knowing: on MCP the per-document mutation gate stays held while the call waits, so a concurrent mutating call on the same document queues behind the review — fine for one user, something to revisit if that ever matters.

• Third outcome — in, and it forced the one deliberate deviation from your response schema: instead of "accepted": true/false, each change reports "outcome": "accepted" | "rejected" | "modified" (plus "pending" for unresolved entries on timeout), since a boolean can't carry the modified case. Everything else matches your shape — review.complete, timed_out, previews, and on timeout the message nudges the agent to ask the user to finish reviewing.

• No auto-save — agreed and dropped; LibreOffice's own save flow covers it.

• Show markup — session start forces the markup visible. (I set the document's ShowChanges property rather than dispatching .uno:ShowTrackedChanges — the dispatch is a toggle, so it would turn markup OFF for someone who already shows changes.)

• Attribution — the scoped global rename works exactly as you reasoned. And it grew into something I really like: a redline's author is fixed at creation time (setting RedlineAuthor afterwards is a silent no-op), so the session swaps the office author between the deletion and the insertion. Insertions are authored "WriterAgent", deletions "WriterAgent (deletions)" — and with the default by-author coloring, new text and removed text render in two distinct colors. Looks great and costs nothing.

• Granularity — I went with B (one ChangeRecord per match/block), but only because I had already tested it reliably, as you conditioned: live over MCP, a replace-all where I accepted some matches and rejected others came back labeled correctly per change. Known edge, noted in the code: two matches in the same paragraph share the paragraph snapshot, so mixed resolutions there can degrade to "modified".

• Scope — Writer-only; style-only edits apply directly and return style_unreviewed: true plus a prompt line telling the agent to mention it (styles still don't produce redlines); compound undo left alone, the session owns the undo story for its mutation; and on/off mid-flight is handled flipping the feature off (or hitting the chat Stop button) ends the wait early, and the user's own tracking state is tracked and restored.

• Undo hygiene (found while testing this) — the per-change anchor bookmarks and the redline tagging were landing on the user's undo stack, so the first one or two Ctrl+Z presses after an agent edit just toggled the invisible wa_review bookmarks and changed nothing visible. Fixed by locking the document undo manager around that bookkeeping (record + cleanup), so the undo stack holds only the real edit — the first Ctrl+Z now reverts the visible change. Verified live (Ctrl+Z in the real UI) and pinned with a regression test.

What the testing surfaced beyond the plan

Turning RecordChanges on isn't quite enough on its own — and this isn't a knock on the existing code. Two of the replace paths are written deliberately, and correctly, in a way that simply predates Track Changes and doesn't compose with recording. Neither is a bug in today's behavior; they just produce messy redlines once recording is on:

• replace_preserving_format diffs char by char on purpose — it touches only the characters that differ, so the untouched parts keep their exact per-character formatting (bold, color, font…). Exactly right for a normal edit. But under recording, each changed character becomes its own redline, so a one-word swap renders as a scrambled, unreviewable mess.
• the inline-markup replace re-applies the paragraph style after inserting, as a guard against the import dropping it — a reasonable precaution. It turns out to be unnecessary (the HTML import keeps the style anyway), and under recording it's actively harmful: re-applying the style across the struck-out old text converts its Delete redline into a Format redline, and accepting a Format keeps the underlying text — so Accept left BOTH the old and the new sentence in the document. (Found live; my reviewer-in-the-loop caught it before I did.)

The fix touches only the recording path and leaves both exactly as they are otherwise: with review off they run byte for byte as today (a flag-off regression test pins that). While recording, the replace becomes one whole-range delete+insert, and the style re-apply is skipped (a heading regression test confirms the style survives without it). The honest trade: a recorded replace gives up per-character formatting preservation in exchange for a clean reviewable redline — which felt right for review mode, where the user is looking at exactly what will land. Happy to revisit if you see a better angle.

One thing on top — separable if you prefer

Reviewing through Edit ▸ Track Changes ▸ Manage felt heavy in practice, and the native UI offers a replace's Delete and Insert as two independent rows — accept one and reject the other and you're left with an incoherent half-resolved paragraph. So on top of the native redlines I added a small inline surface: left-click an agent change → it gets selected (like picking a row in Manage) and a popup opens right at the pointer with Accept/Reject this change, plus accept/reject-all when several are pending; the same entries appear on right-click. It's strictly token-scoped: the user's own tracked changes are never listed or touched — those stay the native UI's business.

Getting the context menu to fire taught me some PyUNO lessons worth passing on: queryInterface(InterfaceClass) can't convert an imported interface class to a UNO type from Python (you call the method directly on the proxy); an exception escaping notifyContextMenuExecute makes the core silently unregister the interceptor forever; and registering on a controller whose view shell isn't attached yet is a silent no-op (register from OnViewCreated's Event.ViewController). Related heads-up: chasing this down, I noticed your Calc cell context menu — the "Edit Python in Cell…" item — never actually registers because of exactly this pitfall. controller.queryInterface(XContextMenuInterception) with the imported IDL class throws "Couldn't convert … to a UNO type" in PyUNO; the try/except around registration swallows it, so registerContextMenuInterceptor is never reached and the item never appears. I confirmed it end to end — ran the real registration against a live Calc frame (it threw and logged "register failed") and right-clicked a cell to see the item is indeed absent; the uno.getTypeByName("com.sun.star.ui.XContextMenuInterception") form returns the interface fine. Happy to send that as a separate small PR. And since the imported-class form fails the same way for any interface, it's possible the same pattern is silently biting in a few other places too — I haven't run those down, so just flagging it as maybe worth a quick sweep.

One more small thing — current master's .oxt fails to bootstrap: plugin/embeddings/ isn't in build_oxt.py's include list, so a fresh install dies with "No module named 'plugin.embeddings'". One-line fix, I'll send it separately.

If you're good with these things, I'll open the PR for you to review.

[KeithCu]

No problem about being busy. That result looks great! It is a complicated feature but I'm glad you didn't get discouraged.

Note you found some good issues, we should look into more later. No one has to fix everything, but as long as it commented, the issues won't get forgotten about. You can put code or docs and ideally both. Send PR when ready. I'm about to make a new release and I'll put it in there.

[KeithCu]

Alright, I put your PR in there. I next moved the setting to the Doc tab, converted the two checkboxes into a dropdown, and hid the timeout value for now since few people will want to adjust it. I'll make other little changes, if it causes any issues, make a PR. Thanks! BTW, please make sure Claude reads AGENTS.md before any task, do you do that?