gmail search: resolve a contact's addresses into an OR query

[chrischall]

Version

v0.19.0 (b25a3c0)

Summary

Searching "mail from this person" is awkward when a contact has multiple addresses
(personal + work). Today you must hand-write from:(a@x.com OR b@y.com). A bare token
like from:alison relies on Gmail's own name/address heuristics and matches
inconsistently versus the fully-qualified addresses.

Since gogcli already has gog contacts search/list (People API) exposing a contact's
emails, a convenience that expands a contact into an OR'd address query would be valuable.

Possible shapes

• A gog gmail search flag, e.g. --from-contact "Alison Hall", that resolves the
  contact's addresses and ORs them into the from:(…) clause; or
• A documented recipe in gmail search --help showing the contacts → OR-query pattern.

Note

This is a cross-surface convenience (contacts → gmail). If it's out of scope for the
gmail command, a short doc cross-reference would still help.

---

Filed from usage of the gogcli-mcp wrapper.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed May 30, 2026, 12:21 AM ET / 04:21 UTC.

Summary
Keep open: current main and v0.19.0 expose Gmail search and contacts separately, but neither a contact-expansion flag nor a documented contacts-to-Gmail OR-query recipe exists. The request fits a small supported-area feature, with the main remaining question being the preferred UX shape.

Reproducibility: not applicable. this is a feature/convenience request rather than a broken existing behavior report. Source and docs inspection show the requested affordance is currently absent.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Next step
This is valid and likely small, but the flag-versus-docs product choice should be made by maintainers before an automated repair lane picks an API shape.

Review details

Best possible solution:

Add the smallest maintainable cross-surface affordance: either a focused Gmail search flag with clear People API errors and tests, or a documented contacts-to-Gmail OR-query recipe if maintainers prefer command composition.

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

Not applicable; this is a feature/convenience request rather than a broken existing behavior report. Source and docs inspection show the requested affordance is currently absent.

Is this the best way to solve the issue?

Unclear; the issue intentionally offers two viable shapes. A docs recipe is the narrowest low-risk solution, while a gog gmail search flag needs maintainer agreement on contact ambiguity, People API scope errors, and command-surface fit.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The exact UX is open: a new Gmail flag would couple Gmail search to People API scope and ambiguity handling, while a docs recipe is lower risk but less convenient.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 929e26b4a999.

Label changes

Label changes:

• add P3: The issue asks for a low-risk cross-command convenience or documentation improvement rather than a broken existing workflow.
• add impact:other: The request affects user ergonomics for a supported Gmail and contacts workflow, but not data loss, auth, session state, or message delivery.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P3: The issue asks for a low-risk cross-command convenience or documentation improvement rather than a broken existing workflow.
• impact:other: The request affects user ergonomics for a supported Gmail and contacts workflow, but not data loss, auth, session state, or message delivery.

Evidence reviewed

What I checked:

• Issue context: The issue reports v0.19.0 and asks for either a gog gmail search flag such as --from-contact or a documented recipe using existing contacts output to form from:(a@x.com OR b@y.com).
• Gmail search command surface: GmailSearchCmd accepts a raw query plus paging/output/timezone flags, then passes the query directly into the Gmail thread list request without resolving People contacts. (internal/cmd/gmail_search.go:14, 929e26b4a999)
• Gmail request construction: newGmailSearchRequestOptions trims the raw query and derives label IDs only; there is no contact-name-to-address expansion layer. (internal/cmd/gmail_search_request.go:10, 929e26b4a999)
• Contacts command surface: Contacts search/list expose a primary email in table and JSON output, while contacts get/raw can return the Person resource; none emits a Gmail OR query helper. (internal/cmd/contacts.go:29, 929e26b4a999)
• Gmail workflow docs: The Gmail workflow guide covers search/read, filters, send guardrails, watches, tracking, and raw Gmail, but no contact-address search recipe. (docs/gmail-workflows.md:11, 929e26b4a999)
• Generated Gmail command docs: The generated gog gmail search page documents raw Gmail query syntax and standard flags only, with no --from-contact flag or contacts cross-reference. (docs/commands/gog-gmail-search.md:1, 929e26b4a999)

Likely related people:

• steipete: Git blame attributes the current Gmail search and contacts command surfaces to the v0.19.0 release commit, and path history/shortlog show Peter Steinberger carrying most recent work in these files. (role: recent area contributor; confidence: high; commits: b25a3c029b37, 7f1ef97e156d, 62a7257aba85; files: internal/cmd/gmail_search.go, internal/cmd/gmail_search_request.go, internal/cmd/contacts.go)
• salmonumbrella: Central-file history includes prior contacts behavior, CLI flag alias/error ergonomics, and Gmail-adjacent workflow work, making this a plausible secondary routing candidate. (role: adjacent contributor; confidence: medium; commits: 3371e3f3ad6d, b8f15931fa0e, 0b0df6589fc8; files: internal/cmd/contacts_crud.go, internal/cmd/contacts.go, internal/cmd/gmail_search.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.