feat(gmail): add signature flags to draft create, update, and forward

[adameq]

Add the existing signature flags to Gmail draft creation, draft updates, and forwards. Resolve the signature for the selected sending identity and place it above quoted or forwarded content. Preserve HTML-only signatures when the input body is plain text. Raw MIME input rejects compose signature flags.

No signature flag means no signature lookup. The shared formatter preserves existing send/reply placement.

Validation: the contributor reported live Gmail draft creation, update, quote, forward, MIME readback, and fixture cleanup. Maintainer validation reproduced and fixed the plain-body/image-only-signature regression, passed the signature fixture suite and full make ci on AWS Crabbox, and completed independent review through P2. Final-head CI is green: https://github.com/openclaw/gogcli/actions/runs/38025911637 and https://github.com/openclaw/gogcli/actions/runs/38025911654.

[clawsweeper]

Codex review: needs real behavior proof before merge.

What this changes

This PR extends the existing optional signature flags to Gmail draft creation, draft updates, and forwarding.

Example: Create a draft with --body 'Hello Alice' --signature when the account signature is 'Kind regards, Sam'.

• Before: Draft creation rejects --signature.
• After: The draft includes the signature below Hello Alice.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	Useful shared implementation with substantial live draft proof and focused regression coverage, limited by one remaining diagnostic defect, an uncovered newer branch, and pending product direction.
Proof confidence	🦐 gold shrimp (3/6)	Real behavior proof is necessary before merge. See Before merge.
Patch quality	🐚 platinum hermit (4/6)	1 actionable review finding remain.

Product

Kind: Feature · Worth it: Needs a maintainer decision · Fix scope: Complete
User problem: Users preparing new, edited, or forwarded drafts cannot request the signature capability already available on send and reply commands.
Reason: The extension has clear practical value and follows the existing design, but exposing new public flags requires an owner direction decision.

Merge readiness

⛔ Blocked before merge - 3 items remain

This PR adds a useful capability still absent from main; the earlier forwarding defects are fixed, while the previously reported draft-update warning defect remains.

Priority: P2
Reviewed head: 9b7ef11cf99d772a42c19083ec7ab6b84b2a93e6
Owner decision: Required. See Decision needed.

Decision needed

• Question: Should the existing signature flags be exposed on draft create/update and both forward commands?
• Recommendation: Approve the signature extension: Accept the focused opt-in extension of an existing Gmail compose capability.
• Why: This adds public command options; maintainer-authored branch repairs show engagement, but the inspected discussion contains no explicit written approval of this PR's expanded command surface.

Before merge

• Add real behavior proof - The real-Gmail CLI transcript proves draft create/update, quote placement, and shared forward composition through stored-MIME readback and cleanup, including image-only forward signatures. It does not exercise the newer plain-body create/update HTML-alternative branch because those commands supply --body-html. Add terminal output or redacted logs showing both commands without --body-html, an image-only signature, and the stored MIME; redact private addresses, IDs, IPs, keys, and non-public endpoints. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Distinguish regenerated HTML from a plain-only draft downgrade (P3) - Updating an existing HTML draft with --body 'New body' and --signature now generates an HTML alternative when the signature contains HTML. runCompose still evaluates the downgrade warning from the caller's empty HTML input and prints 'this update replaces it with plain text only' at line 1047. Preserve the warning about losing the old body formatting, but describe the regenerated HTML result accurately. This previously reported finding remains unchanged at this head.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

• [P3] Distinguish regenerated HTML from a plain-only draft downgrade — internal/cmd/gmail_drafts.go:439-441

Tests

• Missing end-to-end proof: Provide live CLI and stored-MIME evidence for plain-body draft create/update with an image-only signature and no --body-html; the added test covers this branch, but its base-fail/head-pass result is not supplied.

Agent review details

How this fits together

Gmail compose commands turn CLI recipients, sender identity, body, attachments, and optional signatures into RFC822 MIME submitted to Gmail draft or send endpoints.

flowchart TD
  A[CLI compose flags] --> B[Validate inputs]
  B --> C[Resolve sender and signature]
  C --> D[Compose body and quote]
  D --> E[Build RFC822 MIME]
  E --> F[Gmail draft endpoint]
  E --> G[Gmail send endpoint]

Loading

Technical review

Best possible solution:

Extend the shared signature capability while accurately warning about discarded draft formatting and retaining the existing sender, raw-MIME, and no-send contracts.

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

Current-main option structs establish the missing capability, and the introduced HTML-generation branch establishes the diagnostic mismatch; this read-only review ran no target code.

Is this the best way to solve the issue?

Reusing existing signature options and compose builders is a focused implementation that preserves sender selection and dispatch boundaries.

Full review comments:

• [P3] Distinguish regenerated HTML from a plain-only draft downgrade — internal/cmd/gmail_drafts.go:439-441
  Updating an existing HTML draft with --body 'New body' and --signature now generates an HTML alternative when the signature contains HTML. runCompose still evaluates the downgrade warning from the caller's empty HTML input and prints 'this update replaces it with plain text only' at line 1047. Preserve the warning about losing the old body formatting, but describe the regenerated HTML result accurately. This previously reported finding remains unchanged at this head.
  Confidence: 0.99

Overall correctness: patch is correct
Overall confidence: 0.95

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against cf44fccd8174.

Provenance checked

• Shared signature resolution and rendering keeps the original intent (77a16d1: Optional send-as and local-file signatures were implemented for gmail send: Add --signature flag to append Gmail signature #180; its collaborator comment confirms the implementation when local original-blob inspection fails.)
• Draft quote ordering changes intended behavior with a stated reason (feat(gmail): add drafts reply, reply-all, and forward #980: Shared builders separate composition from dispatch; this PR explains resolving the sender and signature before applying the quote.)
• Forward HTML generation changes intended behavior with a stated reason (feat(gmail): add forward command #482: Original forwarding rendered available plain and HTML bodies; this PR explains generating an HTML alternative for plain-only or bodyless originals to preserve HTML signatures.)
• Raw draft conflicts keeps the original intent (feat(gmail): support raw RFC822 drafts #1126: Raw drafts preserve caller MIME and reject compose flags; the new signature flags join that existing conflict boundary.)
• Draft formatting-loss diagnostic keeps the original intent (feat(gmail): warn on rich draft downgrade #957: Warn before plain-only updates remove rich-text formatting while preserving clean JSON output and non-fatal advisory reads.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

• Requested capability remains absent from main: The pinned introduction diff adds composeSignatureOptions to draft create/update and forward options; these command surfaces lack that embedding on fetched main. (internal/cmd/gmail_drafts.go:298, cf44fccd8174)
• Full supplied live proof inspected: The REST-read PR body matches the supplied source identity 308a8671e7b3fd1aff82216f5c391db7f297107563d488e8fbc1d5cd03ff1a2b and contains real-Gmail CLI output, raw-MIME placement checks, and cleanup for draft create/update, quoting, and forwarding; create/update both explicitly supply --body-html. (9b7ef11cf99d)
• Previous diagnostic finding remains: The new builder generates an HTML alternative for plain-body input with an HTML signature, while update still warns that the resulting message is plain text only; the relevant file is unchanged since the previous reviewed head. (internal/cmd/gmail_drafts.go:439, 9b7ef11cf99d)
• Existing diagnostic contract: Maintainer-authored feat(gmail): warn on rich draft downgrade #957 deliberately warns before a plain-only update removes existing rich-text formatting, keeps JSON stdout clean, and makes advisory inspection failures non-fatal. (internal/cmd/gmail_drafts.go:1047, 72aa5b28aff8)
• Established shared composition design: feat(gmail): add drafts reply, reply-all, and forward #980 endorses shared compose builders and separate draft/send dispatch; both forward entry points continue to use the same builder. (internal/cmd/gmail_drafts_compose.go:108, cd965f1d38bb)
• Feature history and local history limit: Scoped history identifies the original signature work, shared-options extraction, forward introduction, and later compose maintenance; collaborator steipete confirms the signature implementation in gmail send: Add --signature flag to append Gmail signature #180. Older blob inspection encounters disabled lazy fetching, so original intent there is supported by that discussion rather than an unread blob. (internal/cmd/gmail_send_signature.go:32, cf44fccd8174)

Likely related people:

• Peter Steinberger: Raw commit cd965f1 adds internal/cmd/gmail_send_signature.go:31 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: cd965f1d38bb; files: internal/cmd/gmail_send_signature.go)
• Malo Bourgon: Raw commit e35aad9 adds internal/cmd/gmail_forward.go:85 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: medium; commits: e35aad920a97; files: internal/cmd/gmail_forward.go)
• spencer-c-reed: Raw commit 13a1aae adds internal/cmd/gmail_forward.go:79 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: medium; commits: 13a1aaea1348; files: internal/cmd/gmail_forward.go)

Review metrics

Metric	Value	Why it matters
Production and test changes	Production +167/-89 lines; tests +541/-1 lines	Most growth verifies CLI composition and emitted MIME across sender, signature, quote, and original-body variants.

Labels

Label changes:

No label changes.

Label justifications:

• P2: This is a useful optional Gmail compose improvement with limited blast radius and unchanged behavior when signature flags are omitted.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only; repair and merge need explicit maintainer commands such as @clawsweeper autofix or @clawsweeper automerge.

History

Review history (4 earlier review cycles)

• reviewed 2026-10-07T13:10:55.777Z sha 06f0c06 :: needs changes before merge. :: [P2] Preserve HTML signatures when forwarding plain-text originals
• reviewed 2026-10-07T14:31:29.905Z sha 0b66e56 :: needs changes before merge. :: [P2] Render HTML signatures for originals without body text
• reviewed 2026-10-07T15:32:18.612Z sha 3cb914d :: needs maintainer review before merge. :: none
• reviewed 2026-10-10T04:23:44.334Z sha ee5ab14 :: needs real behavior proof before merge. :: [P3] Distinguish regenerated HTML from a plain-only draft downgrade

Reviewed October 10, 2026, 1:03 AM ET / 05:03 UTC (Revision 5).

[steipete]

Landed as cae4fdc. Thanks @adameq for the implementation and live draft proof. The maintainer pass fixed image-only signatures on plain-text drafts; the regression suite, full AWS Crabbox gate, and final-head platform/Docker CI passed. Your contributor credit is preserved in the squash commit.