feat(docs): read-only surface for suggested edits (tracked changes) — docs suggestions list / --suggestions

[sebsnyk]

What I'm trying to do

Read the pending suggested edits (tracked changes) on a Google Doc from the CLI — the per-run inserted/deleted text a reviewer has proposed but not yet accepted — so a caller can see "what is being suggested on this doc" without opening it in the browser.

Gap (confirmed in CLI + source, v0.30.0)

There is no surface for Docs suggestions:

• gog docs --help, gog docs cat --help expose no --suggestions flag and no suggestions subcommand. The DocsCmd struct in internal/cmd/docs.go has no suggestions command.
• No Documents.Get call sets SuggestionsViewMode — grep -rn "SuggestionsViewMode(" returns nothing. docs raw (the lossless dumper) calls svc.Documents.Get(id) without .SuggestionsViewMode("SUGGESTIONS_INLINE"), so it returns the default view, where per-run suggestedInsertionIds / suggestedDeletionIds are not reliably populated. The struct field is only copied through in projectRawDocumentTab (SuggestionsViewMode: doc.SuggestionsViewMode), never set on the request.
• Nothing renders suggestedInsertionIds / suggestedDeletionIds / suggestedTextStyleChanges — grep -rn "SuggestedInsertionIds\|SuggestedDeletionIds" (excluding tests) returns nothing.

So today there is no way, raw or rendered, to reliably get a doc's pending suggestions out of gog.

Why this is feasible (Docs API)

The Docs REST API supports reading suggestions. documents.get accepts a suggestionsViewMode query parameter; with SUGGESTIONS_INLINE the response carries per-TextRun suggestedInsertionIds and suggestedDeletionIds, plus document-level suggestedDocumentStyleChanges / suggestedNamedStylesChanges and per-element style-change maps. Ref: https://developers.google.com/docs/api/reference/rest/v1/documents/get and the view-mode docs at https://developers.google.com/docs/api/reference/rest/v1/documents#Document.SuggestionsViewMode

gog already reaches this exact tree via docs raw; the only missing pieces are (1) setting the view mode on the request and (2) walking the runs to surface the suggested insertions/deletions.

Scope: READ-ONLY (known API ceiling)

Accepting or rejecting suggestions is not in the Docs API — there is no acceptSuggestion / rejectSuggestion request; accept/reject is UI-only. This issue is intentionally read-only surfacing. Please do not scope it to mutation.

Also note this is distinct from comments and from #672:

• Comments are a Drive-level surface already covered by docs comments / drive comments — a different object from suggestions.
• Expose Google Docs version history (revisions list/get) for diffing #672 (version-history diffing) is a different mechanism; it asserts suggestion ids are "already accessible" via docs raw, but in practice they aren't, because the view mode is never set. This issue closes that actual gap.

Proposed surface

A read-only command:

gog docs suggestions list <docId> [--tab <title|id>]

For each pending suggestion, print the suggestion id, kind (insertion / deletion), the affected text, and — where the API exposes it (it surfaces suggestion ids; author attribution is limited) — any available range/context. Honour -j/--json for the structured form and -p/--plain (TSV) for scripting.

Optionally, a lighter alternative for parity with existing read paths:

gog docs cat <docId> --suggestions     # inline-mark suggested insertions/deletions in the text output
gog docs raw <docId> --suggestions     # set SuggestionsViewMode=SUGGESTIONS_INLINE on the Get call so ids actually populate

Either way the load-bearing fix is: issue Documents.Get with SuggestionsViewMode=SUGGESTIONS_INLINE and walk body.content[].paragraph.elements[].textRun.{suggestedInsertionIds,suggestedDeletionIds}.

Other Workspace surfaces (scoped out, verified)

Sheets and Slides have no Docs-style suggestions / tracked-changes mode — gog sheets --help and gog slides --help expose nothing, and the underlying Sheets/Slides APIs have no suggestions view-mode equivalent. So this should stay Docs-only and not over-promise a generic "tracked changes" surface.

Version

v0.30.0 (Homebrew 2026-06-22)

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 26, 2026, 2:18 PM ET / 18:18 UTC.

Summary
Keep open: current main and the latest release still lack the requested Docs suggestions surface. Source inspection shows no docs suggestions command, no --suggestions read mode, and no Docs Documents.Get call that requests SuggestionsViewMode("SUGGESTIONS_INLINE"); the related revisions work covers Drive revision metadata, not pending Docs tracked changes.

Reproducibility: not applicable. as a bug reproduction: this is a feature request. Source inspection gives high confidence that current main lacks the requested command or flag and never sets the Docs suggestions view mode.

Root-cause cluster
Relationship: canonical
Canonical: #876
Summary: This issue is the canonical remaining tracked-suggestions request; the related revisions issue and merged PR are adjacent Drive revision metadata work, not the same root cause.

Members:

• adjacent_distinct: Expose Google Docs version history (revisions list/get) for diffing #672 - That closed issue requested Docs version/revision history for diffing, not pending tracked suggestions.
• adjacent_distinct: feat(drive): add revision metadata commands #748 - That merged PR added Drive revision metadata and export-link commands; it does not fetch SUGGESTIONS_INLINE Docs data.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
Maintainers need to choose the command or flag contract and live Google proof bar before implementation, so this should stay in manual review rather than queueing an automated fix PR.

Review details

Best possible solution:

Define a narrow read-only Docs suggestions surface that requests SUGGESTIONS_INLINE, emits stable JSON/plain output, supports tab selection where feasible, and explicitly leaves accept/reject mutation out of scope.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this is a feature request. Source inspection gives high confidence that current main lacks the requested command or flag and never sets the Docs suggestions view mode.

Is this the best way to solve the issue?

Unclear until maintainers choose the CLI contract. A dedicated read-only list command plus optional raw support looks maintainable, while accept/reject mutation should remain out of scope.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A live Google Doc with pending suggestions still needs to validate insertion/deletion grouping, tab behavior, style-change maps, and any attribution Google exposes.
• Maintainers still need to choose the public contract: a dedicated docs suggestions list, a --suggestions mode on docs raw or docs cat, or a narrower first step.

Codex review notes: model internal, reasoning high; reviewed against 213ddb60d7d1.

Label changes

Label changes:

• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P2: This is a bounded improvement in an existing Docs area with clear automation value and limited blast radius.
• impact:other: The issue affects scriptable access to Google Docs suggested edits, which is a concrete CLI capability gap outside the more specific owned impact categories.

Evidence reviewed

Acceptance criteria:

• go test ./internal/cmd
• Live Google Docs smoke with a document containing pending suggested insertions and deletions; verify JSON/plain output and tab behavior if included.

What I checked:

• Docs command surface has no suggestions subcommand: DocsCmd registers the current Docs subcommands, including cat, comments, paragraphs, and raw, but no suggestions command. (internal/cmd/docs.go:18, 213ddb60d7d1)
• Raw read path does not request inline suggestions: DocsRawCmd builds svc.Documents.Get(id).Context(ctx) and only adds IncludeTabsContent(true) for tab modes; it never sets SuggestionsViewMode("SUGGESTIONS_INLINE"). (internal/cmd/docs.go:105, 213ddb60d7d1)
• Cat read path has no suggestions flag or view mode: DocsCatCmd exposes docId, max-bytes, tab, all-tabs, raw, and numbered, and its Documents.Get calls do not request a suggestions view mode. (internal/cmd/docs_read.go:19, 213ddb60d7d1)
• No non-test setter or renderer found: Repository search found no non-test .SuggestionsViewMode( call and no non-test references to the requested suggested insertion/deletion fields; existing hits only copy the response field through raw tab projection or test fixtures. (213ddb60d7d1)
• Generated command docs confirm no user-facing surface: The generated gog docs command page lists current Docs subcommands and has no gog docs suggestions entry; gog docs raw and gog docs cat docs also have no --suggestions flag. (docs/commands/gog-docs.md:17, 213ddb60d7d1)
• Latest release shares the inspected Docs surface: Current main differs from v0.31.1 only in CHANGELOG.md and internal/cmd/VERSION, so the inspected Docs command/read/docs files are unchanged from the latest release. (608aa46e7b9c)

Likely related people:

• steipete: Introduced the lossless raw command, added tab-aware raw output, and has the dominant recent history in the inspected Docs command/read files. (role: recent Docs raw/read area contributor; confidence: high; commits: 7b288cc92278, 0a7e6425384b, e51f6be9dc38; files: internal/cmd/docs.go, internal/cmd/docs_read.go, internal/cmd/docs_raw_test.go)
• Alex Hillman: Introduced Docs tab support and the read/edit command structure that a --tab suggestions implementation would need to preserve. (role: Docs tabs/read feature introducer; confidence: medium; commits: 2f5131995552; files: internal/cmd/docs.go, internal/cmd/docs_commands_test.go)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.