You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by po...@apache.org on 2026/05/04 21:03:09 UTC
(airflow-steward) branch main updated: refactor(gmail): use replyToMessageId; oauth_curl now opt-in (#49)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 7d2f17a refactor(gmail): use replyToMessageId; oauth_curl now opt-in (#49)
7d2f17a is described below
commit 7d2f17a45a4a1c16bbb6b8940e0904f35bbac5e8
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Mon May 4 23:03:03 2026 +0200
refactor(gmail): use replyToMessageId; oauth_curl now opt-in (#49)
The claude.ai Gmail MCP `create_draft` tool now accepts a
`replyToMessageId` parameter. Verified end-to-end against a real
Gmail thread: the draft attaches to the inbound conversation on the
sender's Gmail and surfaces in both the conversation view and the
global Drafts folder.
Flip the framework's precedence rule accordingly:
- `claude_ai_mcp` (default) is now the recommended path. Skills
resolve the inbound thread's chronologically-last message ID via
`get_thread` and pass it as `replyToMessageId` on `create_draft`.
- `oauth_curl` is now opt-in. It remains useful when a `threadId` is
on hand without an extra `get_thread` round-trip and as the only
path that lets the skills delete drafts via the Gmail API; the
bulk `oauth-draft-mark-read` script has no MCP equivalent.
Updates: tools/gmail/{operations,draft-backends,threading,tool,
asf-relay}.md, oauth-draft/README.md, AGENTS.md, CONTRIBUTING.md,
and per-skill drafting steps in security-cve-allocate,
security-issue-import, security-issue-invalidate, security-issue-sync.
The pile-up known-issue is generalised to apply to thread-attached
drafts on either backend.
Co-authored-by: Claude Opus 4.7 (1M context) <no...@anthropic.com>
---
.claude/skills/security-cve-allocate/SKILL.md | 37 ++-
.claude/skills/security-issue-import/SKILL.md | 30 +--
.claude/skills/security-issue-invalidate/SKILL.md | 32 +--
.claude/skills/security-issue-sync/SKILL.md | 77 +++---
AGENTS.md | 22 +-
CONTRIBUTING.md | 2 +-
tools/gmail/asf-relay.md | 8 +-
tools/gmail/draft-backends.md | 272 +++++++++++-----------
tools/gmail/oauth-draft/README.md | 15 +-
tools/gmail/operations.md | 50 ++--
tools/gmail/threading.md | 108 ++++-----
tools/gmail/tool.md | 26 ++-
12 files changed, 351 insertions(+), 328 deletions(-)
diff --git a/.claude/skills/security-cve-allocate/SKILL.md b/.claude/skills/security-cve-allocate/SKILL.md
index 77b91d5..8b9bdac 100644
--- a/.claude/skills/security-cve-allocate/SKILL.md
+++ b/.claude/skills/security-cve-allocate/SKILL.md
@@ -431,29 +431,26 @@ user to confirm. Numbered items:
inbound thread per the *Detecting drafts that already exist on a
thread* section of
[`tools/gmail/draft-backends.md`](../../../tools/gmail/draft-backends.md#detecting-drafts-that-already-exist-on-a-thread)
- — run **both** `mcp__claude_ai_Gmail__list_drafts` (catches
- `claude_ai_mcp` drafts in the global Drafts folder) **and**
- `mcp__claude_ai_Gmail__get_thread` on the inbound `threadId`
- (catches `oauth_curl` drafts attached by `threadId` that may not
- surface in the global Drafts folder). Re-ask the credit-preference
- question **only if it has not yet been asked** on the thread —
- never ping twice.
-
- **Never send.** Always create a Gmail draft via the project's
- preferred drafting backend per the precedence rule in
- [`tools/gmail/draft-backends.md`](../../../tools/gmail/draft-backends.md#how-the-skills-pick-a-backend):
- **probe for `oauth_curl` credentials first** (default path
- `~/.config/apache-steward/gmail-oauth.json`); use `oauth_curl` when
- present so the draft is `threadId`-attached, only fall back to
- `claude_ai_mcp` (subject-matched) when oauth credentials are not
- on disk. The `tools.gmail.draft_backend` config field acts as an
- explicit override only when set to `claude_ai_mcp_force`. Resolve
- the `threadId` from the tracker's *security-thread* body field
+ — run **both** `mcp__claude_ai_Gmail__list_drafts` (catches drafts
+ in the global Drafts folder) **and** `mcp__claude_ai_Gmail__get_thread`
+ on the inbound `threadId` (catches thread-attached drafts that may
+ pile up and hide from the global Drafts folder, regardless of
+ backend). Re-ask the credit-preference question **only if it has
+ not yet been asked** on the thread — never ping twice.
+
+ **Never send.** Create a Gmail draft via the project's configured
+ drafting backend per
+ [`tools/gmail/draft-backends.md`](../../../tools/gmail/draft-backends.md#how-the-skills-pick-a-backend).
+ The default and recommended path is the `claude_ai_mcp` backend
+ with `replyToMessageId` set to the chronologically-last message ID
+ on the inbound thread (resolve it via `get_thread`); the opt-in
+ `oauth_curl` backend uses `threadId` instead. Resolve the
+ `threadId` from the tracker's *security-thread* body field
(for Airflow, *"Security mailing list thread"*); subject is always
`Re: <root subject of the inbound report>`, never fabricated.
Surface which backend was used and which threading path the draft
- took (`threadId`-attached vs subject fallback) in the Step 5
- proposal. See [`tools/gmail/threading.md`](../../../tools/gmail/threading.md)
+ took (thread-attached vs subject fallback) in the Step 5 proposal.
+ See [`tools/gmail/threading.md`](../../../tools/gmail/threading.md)
for the full threading rule including the few cases where the
skill should stop rather than fall back.
diff --git a/.claude/skills/security-issue-import/SKILL.md b/.claude/skills/security-issue-import/SKILL.md
index 63bd4df..13540ff 100644
--- a/.claude/skills/security-issue-import/SKILL.md
+++ b/.claude/skills/security-issue-import/SKILL.md
@@ -972,18 +972,17 @@ For each confirmed `Report` / `ASF-security relay`:
the item is already on the board with the same Status.
4. Draft the receipt-of-confirmation reply. **The draft must be
- created on the inbound Gmail thread** — always pass the candidate's
- `threadId` to the project's preferred drafting backend per the
- precedence rule in
- [`tools/gmail/draft-backends.md`](../../../tools/gmail/draft-backends.md#how-the-skills-pick-a-backend):
- **probe for `oauth_curl` credentials first** (default path
- `~/.config/apache-steward/gmail-oauth.json`); use `oauth_curl` when
- present so the draft is `threadId`-attached, only fall back to
- `claude_ai_mcp` (subject-matched) when oauth credentials are not
- on disk. The `tools.gmail.draft_backend` config field acts as an
- explicit override only when set to `claude_ai_mcp_force`. Surface
- in the proposal which backend was used and which path the draft
- took (`threadId`-attached vs subject fallback).
+ created on the inbound Gmail thread** via the project's configured
+ drafting backend per
+ [`tools/gmail/draft-backends.md`](../../../tools/gmail/draft-backends.md#how-the-skills-pick-a-backend).
+ The default `claude_ai_mcp` backend resolves the candidate's
+ chronologically-last message ID (call
+ `mcp__claude_ai_Gmail__get_thread(threadId=<candidate>,
+ messageFormat='MINIMAL')` and take `messages[-1].id`) and passes
+ it to `mcp__claude_ai_Gmail__create_draft` as `replyToMessageId`.
+ The opt-in `oauth_curl` backend uses `--thread-id` directly.
+ Surface in the proposal which backend was used and which path the
+ draft took (thread-attached vs subject fallback).
**Before drafting, check for an existing pending draft** on the
inbound thread per the *Detecting drafts that already exist on a
@@ -991,9 +990,10 @@ For each confirmed `Report` / `ASF-security relay`:
[`draft-backends.md`](../../../tools/gmail/draft-backends.md#detecting-drafts-that-already-exist-on-a-thread)
— run **both** `mcp__claude_ai_Gmail__list_drafts` and
`mcp__claude_ai_Gmail__get_thread` (scan messages for `DRAFT`
- labels) so `oauth_curl`-attached drafts are not missed. If a
- pending draft already exists, surface it to the user instead of
- silently shadowing it with a second draft.
+ labels) so thread-attached drafts that may have piled up and
+ hidden from the global Drafts folder are not missed. If a pending
+ draft already exists, surface it to the user instead of silently
+ shadowing it with a second draft.
Never fabricate a new subject — subject is always
`Re: <root subject>`, even when the recipient changes.
diff --git a/.claude/skills/security-issue-invalidate/SKILL.md b/.claude/skills/security-issue-invalidate/SKILL.md
index a98f96e..6382ffa 100644
--- a/.claude/skills/security-issue-invalidate/SKILL.md
+++ b/.claude/skills/security-issue-invalidate/SKILL.md
@@ -136,7 +136,7 @@ Before running, the skill needs:
See [Prerequisites for running the agent skills](../../../README.md#prerequisites-for-running-the-agent-skills)
in `README.md` for overall setup and the
-[`oauth_curl` vs `claude_ai_mcp` precedence rule](../../../tools/gmail/draft-backends.md#how-the-skills-pick-a-backend)
+[`claude_ai_mcp` (default) vs `oauth_curl` (opt-in) backend rule](../../../tools/gmail/draft-backends.md#how-the-skills-pick-a-backend)
for the Gmail draft path.
---
@@ -405,9 +405,9 @@ For `security@`-imported trackers:
value comes from
[`<project-config>/project.md`](../../../<project-config>/project.md#gmail-and-ponymail).
2. **Subject:** `Re: <root subject>`. Never invent a fresh
- subject — the reply lands on the inbound thread (when
- `oauth_curl` is the backend) or is subject-matched into it
- (when `claude_ai_mcp` is the backend).
+ subject — the reply lands on the inbound thread via
+ thread attachment (`replyToMessageId` for `claude_ai_mcp`,
+ `--thread-id` for `oauth_curl`).
3. **Body:**
- Spine: the canned section picked in Step 4, verbatim.
- Augmentation: a clearly-marked block filling the
@@ -427,12 +427,14 @@ For `security@`-imported trackers:
the team's position once, clearly, with reasoning. Do not
re-open the discussion with phrases like *"happy to
discuss further"* — close the loop.
-4. **Backend selection:** probe for `oauth_curl` credentials
- first (default path
- `~/.config/apache-steward/gmail-oauth.json`) per
- [`tools/gmail/draft-backends.md`](../../../tools/gmail/draft-backends.md#how-the-skills-pick-a-backend);
- fall back to `claude_ai_mcp` (subject-matched) when
- credentials are not on disk.
+4. **Backend selection:** use the project's configured
+ drafting backend per
+ [`tools/gmail/draft-backends.md`](../../../tools/gmail/draft-backends.md#how-the-skills-pick-a-backend).
+ Default is `claude_ai_mcp` with `replyToMessageId` thread
+ attachment; the opt-in `oauth_curl` backend is used when
+ `tools.gmail.draft_backend: oauth_curl` is set and
+ credentials are on disk (default path
+ `~/.config/apache-steward/gmail-oauth.json`).
5. **Existing-draft check.** Before drafting, scan the inbound
thread for an existing pending draft per the
[*Detecting drafts that already exist on a thread*](../../../tools/gmail/draft-backends.md#detecting-drafts-that-already-exist-on-a-thread)
@@ -576,14 +578,18 @@ Skip if PR-imported or the user chose `silent`.
Use the backend chosen in Step 5d:
+- **`claude_ai_mcp`:** call `mcp__claude_ai_Gmail__get_thread`
+ on `<tracker.threadId>` with `messageFormat: MINIMAL`, take
+ the chronologically-last message's `id`, and call
+ `mcp__claude_ai_Gmail__create_draft` with `to=<reporterEmail>`,
+ `cc=<security-list>`, `subject='Re: <root subject>'`,
+ `body=<file>`, and `replyToMessageId=<that message id>`. The
+ draft lands attached to the inbound thread.
- **`oauth_curl`:** call the `oauth_curl drafts:create` script
per [`draft-backends.md`](../../../tools/gmail/draft-backends.md)
with `threadId=<tracker.threadId>`, `to=<reporterEmail>`,
`cc=<security-list>`, `subject='Re: <root subject>'`,
`body=<file>`. The draft lands attached to the inbound thread.
-- **`claude_ai_mcp`:** call
- `mcp__claude_ai_Gmail__create_draft` with the same fields;
- Gmail subject-matches it onto the inbound thread.
Capture the returned `draftId`. Update the rollup entry's
*Reporter notification* line with the actual draft ID
diff --git a/.claude/skills/security-issue-sync/SKILL.md b/.claude/skills/security-issue-sync/SKILL.md
index 8364ce4..0dee295 100644
--- a/.claude/skills/security-issue-sync/SKILL.md
+++ b/.claude/skills/security-issue-sync/SKILL.md
@@ -1615,10 +1615,12 @@ will change and *why*. Group them by category:
section of [`AGENTS.md`](../../../AGENTS.md).
**Never send.** Always create a draft. Prefer attaching it to the
- inbound mail thread by `threadId` (from Step 1c); if Step 1c
- could not resolve a `threadId`, fall back to a subject-matched
- draft (`threadId` omitted, `subject: Re: <root subject>`) per the
- threading rule in
+ inbound mail thread (the default `claude_ai_mcp` backend resolves
+ the latest message ID from the inbound `threadId` and passes it as
+ `replyToMessageId`; the opt-in `oauth_curl` backend uses
+ `--thread-id` directly). If Step 1c could not resolve a `threadId`,
+ fall back to a subject-matched draft (thread-attachment parameter
+ omitted, `subject: Re: <root subject>`) per the threading rule in
[`tools/gmail/threading.md`](../../../tools/gmail/threading.md).
Surface which path was taken in the proposal. The Gmail MCP's
no-update-no-delete limitation — and the resulting rule that
@@ -1840,48 +1842,47 @@ before moving on to the next item. Use:
`updateProjectV2ItemFieldValue`). Re-fetch the option IDs via the
introspection query in the same reference if a write mutation
starts returning `not found`.
-- **Gmail draft:** create via the project's preferred drafting
- backend per the precedence rule in
- [`tools/gmail/draft-backends.md`](../../../tools/gmail/draft-backends.md#how-the-skills-pick-a-backend).
- **`oauth_curl` is preferred whenever its credentials are on disk**
- (probe order: `tools.gmail.oauth_credentials_path` →
- `$GMAIL_OAUTH_CREDENTIALS` → default `~/.config/apache-steward/gmail-oauth.json`),
- regardless of what `tools.gmail.draft_backend` is set to. The
- config field acts as an explicit override only when set to
- `claude_ai_mcp_force`. Per-backend call shape:
-
- - **`oauth_curl`** (preferred) — invoke
+- **Gmail draft:** create via the project's configured drafting
+ backend per [`tools/gmail/draft-backends.md`](../../../tools/gmail/draft-backends.md#how-the-skills-pick-a-backend).
+ The default and recommended backend is `claude_ai_mcp` with
+ thread attachment via `replyToMessageId`. Per-backend call shape:
+
+ - **`claude_ai_mcp`** (default) — first call
+ `mcp__claude_ai_Gmail__get_thread(threadId=<from Step 1c>,
+ messageFormat='MINIMAL')` to resolve the chronologically-last
+ message ID; then call `mcp__claude_ai_Gmail__create_draft` with
+ `subject="Re: <root subject>"`, the standard `to` / `cc` / `body`,
+ and `replyToMessageId=<that message id>`. The draft attaches to
+ the inbound thread on the sender's Gmail and surfaces in both the
+ conversation view and the global Drafts folder.
+ - **`oauth_curl`** (opt-in for users who set
+ `tools.gmail.draft_backend: oauth_curl` and have credentials at
+ `tools.gmail.oauth_credentials_path` /
+ `$GMAIL_OAUTH_CREDENTIALS` / default
+ `~/.config/apache-steward/gmail-oauth.json`) — invoke
`uv run --project <framework>/tools/gmail/oauth-draft oauth-draft-create`
(see [`tools/gmail/oauth-draft/README.md`](../../../tools/gmail/oauth-draft/README.md))
with `--thread-id` from Step 1c, the standard `--to` / `--cc`,
- `--subject "Re: <root subject>"`, and a `--body-file`. Threads
- on every client (including the sender's own Gmail view).
- - **`claude_ai_mcp`** (fallback only when oauth credentials are
- not configured) — call `mcp__claude_ai_Gmail__create_draft` with
- the same subject/to/cc/body. The MCP does not accept `threadId`,
- so threading relies on subject-matched fallback; see the
- [fallback rule](../../../tools/gmail/threading.md#fallback--subject-matched-draft-when-threadid-is-unavailable).
+ `--subject "Re: <root subject>"`, and a `--body-file`.
**Before drafting, check for an existing pending draft on the
thread.** Run **both** `mcp__claude_ai_Gmail__list_drafts` (catches
- `claude_ai_mcp` drafts which surface in the global Drafts folder)
- **and** `mcp__claude_ai_Gmail__get_thread` on the inbound `threadId`
- with `messageFormat: MINIMAL`, scanning each message for a `DRAFT`
- label (catches `oauth_curl` drafts which attach by `threadId` and
- may not surface in the global Drafts folder when several pile up).
- Per-thread detection is required when oauth credentials are
- configured — `list_drafts` alone misses thread-attached drafts.
- See the *Detecting drafts that already exist on a thread* section
- of [`draft-backends.md`](../../../tools/gmail/draft-backends.md#detecting-drafts-that-already-exist-on-a-thread).
+ drafts in the global Drafts folder) **and**
+ `mcp__claude_ai_Gmail__get_thread` on the inbound `threadId` with
+ `messageFormat: MINIMAL`, scanning each message for a `DRAFT` label
+ (catches thread-attached drafts that may pile up and hide from the
+ global Drafts folder, regardless of backend). `list_drafts` alone
+ misses thread-attached drafts under pile-up. See the *Detecting
+ drafts that already exist on a thread* section of
+ [`draft-backends.md`](../../../tools/gmail/draft-backends.md#detecting-drafts-that-already-exist-on-a-thread).
**Surface which backend and which threading path the draft took**
- (`threadId`-attached via `oauth_curl`, or subject fallback via
- `claude_ai_mcp`) in the proposal so the user can see the threading
- at a glance; record the backend + reason on the tracker's status
- comment when subject fallback kicks in (so a future triager
- understands why the threading degraded). **Never send** — both
- backends create drafts only. Tell the user the draft is waiting
- for their review in Gmail.
+ (thread-attached vs subject fallback) in the proposal so the user
+ can see the threading at a glance; record the backend + reason on
+ the tracker's status comment when subject fallback kicks in (so a
+ future triager understands why the threading degraded). **Never
+ send** — both backends create drafts only. Tell the user the
+ draft is waiting for their review in Gmail.
If any command fails, stop the apply loop, report the failure, and ask the user
how to proceed — do not guess.
diff --git a/AGENTS.md b/AGENTS.md
index a8b8659..6b897c9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -924,13 +924,17 @@ under this rule.
### Threading: drafts stay on the inbound Gmail thread
Every drafted email that relates to a tracking issue **should**
-attach to the original inbound Gmail thread. The preferred path is
-to pass the inbound `threadId` to `create_draft`; the pragmatic
-fallback — when the `threadId` cannot be resolved — is to omit it
-and create the draft with the matching `Re: <root subject>` line,
-which most clients still thread by subject. The full rule (when
-each path applies, when to stop instead, how to surface the
-degraded threading in the skill's proposal) lives in
+attach to the original inbound Gmail thread. On the default
+`claude_ai_mcp` backend, that means resolving the thread's latest
+message ID (via `get_thread`) and passing it to `create_draft` as
+`replyToMessageId`; on the opt-in `oauth_curl` backend it means
+passing the `threadId` to `oauth-draft-create --thread-id`. The
+pragmatic fallback — when the inbound thread cannot be resolved —
+is to omit the thread-attachment parameter and create the draft
+with the matching `Re: <root subject>` line, which most clients
+still thread by subject. The full rule (when each path applies,
+when to stop instead, how to surface the degraded threading in the
+skill's proposal) lives in
[`tools/gmail/threading.md`](tools/gmail/threading.md).
### ASF-security-relay reports: a special case for drafting
@@ -939,8 +943,8 @@ Some reports reach the project's security list via the ASF security
team (from `security@apache.org`, or a personal `@apache.org` address
of an ASF-security-team member) rather than from the external reporter
directly. The drafting rules for that case — different `To:`, same
-threading behaviour (prefer `threadId`, fall back to the inbound
-subject), terse body — live in
+threading behaviour (attach to the inbound thread, fall back to the
+inbound subject when the thread cannot be resolved), terse body — live in
[`tools/gmail/asf-relay.md`](tools/gmail/asf-relay.md). The detection
signals the `security-issue-import` skill uses to classify a candidate
as a relay live in that skill's Step 3.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d403615..c88b43b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -120,7 +120,7 @@ four — no hard-coded project assumptions anywhere.
│ ├── gmail/
│ │ ├── tool.md # Adapter overview
│ │ ├── operations.md # MCP call signatures + no-update-no-delete rule
-│ │ ├── threading.md # threadId and subject-matched fallback
+│ │ ├── threading.md # Thread attachment and subject-matched fallback
│ │ ├── search-queries.md # Canonical reusable query templates
│ │ ├── ponymail-archive.md
│ │ └── asf-relay.md
diff --git a/tools/gmail/asf-relay.md b/tools/gmail/asf-relay.md
index 81bde08..d0bee07 100644
--- a/tools/gmail/asf-relay.md
+++ b/tools/gmail/asf-relay.md
@@ -36,8 +36,12 @@ Placeholder convention:
## Rules
-- **`threadId`** — the inbound relay thread's `threadId`, per the
- [threading rule](threading.md). Never fabricate a new thread for
+- **Thread attachment** — attach the draft to the inbound relay
+ thread, per the [threading rule](threading.md). On the default
+ `claude_ai_mcp` backend that means resolving the thread's latest
+ message ID and passing it as `replyToMessageId`; on the opt-in
+ `oauth_curl` backend it means passing the `threadId` to
+ `oauth-draft-create --thread-id`. Never fabricate a new thread for
a credit-preference relay; it goes on the same thread as the
original inbound report.
- **Subject** — `Re: <root subject>`, i.e. the subject of the
diff --git a/tools/gmail/draft-backends.md b/tools/gmail/draft-backends.md
index 5457528..195f309 100644
--- a/tools/gmail/draft-backends.md
+++ b/tools/gmail/draft-backends.md
@@ -7,11 +7,10 @@
- [How the skills pick a backend](#how-the-skills-pick-a-backend)
- [Detecting drafts that already exist on a thread](#detecting-drafts-that-already-exist-on-a-thread)
- [Limitations that apply to both backends](#limitations-that-apply-to-both-backends)
- - [Known issue — `oauth_curl` thread-attached drafts may not surface in the global Drafts folder](#known-issue--oauth_curl-thread-attached-drafts-may-not-surface-in-the-global-drafts-folder)
+ - [Known issue — thread-attached drafts may not surface in the global Drafts folder when stacked](#known-issue--thread-attached-drafts-may-not-surface-in-the-global-drafts-folder-when-stacked)
- [Recommended workflow when re-drafting on a thread that already carries a pending draft](#recommended-workflow-when-re-drafting-on-a-thread-that-already-carries-a-pending-draft)
- [Concrete steps when the pile-up has already happened](#concrete-steps-when-the-pile-up-has-already-happened)
- [When this rule does not apply](#when-this-rule-does-not-apply)
- - [Migration — when the claude.ai MCP adds `threadId`](#migration--when-the-claudeai-mcp-adds-threadid)
- [Referenced by](#referenced-by)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -25,10 +24,10 @@ The skills create Gmail drafts via one of two backends, selected by the
user in `.apache-steward-overrides/user.md` under
`tools.gmail.draft_backend`:
-| Backend | Value | `threadId` attach? | Setup |
+| Backend | Value | Thread attach? | Setup |
|---|---|---|---|
-| claude.ai Gmail MCP | `claude_ai_mcp` (default) | **no** (subject-matched fallback only) | none — works as soon as the Gmail connector is authenticated on claude.ai |
-| OAuth + `curl` script | `oauth_curl` | **yes** | one-time Google OAuth client + refresh-token setup, automated via `uv run --project <framework>/tools/gmail/oauth-draft oauth-draft-setup` — see [`oauth-draft/README.md`](oauth-draft/README.md) |
+| claude.ai Gmail MCP | `claude_ai_mcp` (default, recommended) | **yes** — via `replyToMessageId` (a message ID resolved from the inbound thread) | none — works as soon as the Gmail connector is authenticated on claude.ai |
+| OAuth + `curl` script | `oauth_curl` | **yes** — via `threadId` (and explicit `In-Reply-To` / `References` headers) | one-time Google OAuth client + refresh-token setup, automated via `uv run --project <framework>/tools/gmail/oauth-draft oauth-draft-setup` — see [`oauth-draft/README.md`](oauth-draft/README.md) |
Both backends create **drafts** — never send. The human review-and-send
step is still required before any outbound message leaves the user's
@@ -36,37 +35,61 @@ Gmail.
## Why there are two
-The first-party claude.ai Gmail MCP is easy to set up and exposes
-everything the skills need for reading, searching, and listing drafts.
-It is the default.
-
-The MCP's `create_draft` tool, however, does not accept a `threadId`
-parameter — a gap between the underlying Gmail REST API (which
-supports it on `drafts.create`) and the MCP's surface area. As a
-consequence, drafts created via the MCP start a new conversation on
-the **sender's** Gmail side. Recipients' mail clients thread-match by
-subject (`Re: <exact subject>` + matching `In-Reply-To` / `References`
-chain) and usually attach the reply correctly on their side, but the
-sender sees a new conversation in their drafts queue. That makes
-pre-send auditing harder and means subsequent sync runs cannot rely
-on a single `threadId` to find every draft for a tracker.
-
-The `oauth_curl` backend closes the gap by talking to the Gmail REST
-API directly, with a user-provided refresh token. It is opt-in because
-it requires a one-time OAuth setup (create a Google Cloud OAuth
-client, obtain a refresh token, drop it in a credentials file).
+The first-party claude.ai Gmail MCP is easy to set up and now exposes
+everything the skills need for reading, searching, listing drafts,
+**and creating thread-attached drafts** via `replyToMessageId`. It is
+the default and the recommended backend for almost every adopter.
+
+Historically the MCP's `create_draft` tool did not plumb through a
+`threadId` parameter, which forced thread-attached drafts down the
+`oauth_curl` path. That gap closed when the MCP added
+`replyToMessageId` (a Gmail *message* ID — Gmail attaches the draft
+to the conversation containing that message). The `oauth_curl`
+backend remains in the toolchain because it offers two capabilities
+the MCP still does not:
+
+- **`threadId`-keyed draft creation** — useful when only a `threadId`
+ is on hand (e.g. from an old tracker rollup) and re-fetching the
+ thread to extract the latest message ID is not worth a round-trip.
+- **Bulk read/modify operations** — `oauth-draft-mark-read`
+ (label-modify on a query result set) has no MCP equivalent.
+
+If you do not need either of those, **stay on the default
+`claude_ai_mcp` backend**. The OAuth setup, refresh-token rotation,
+and credentials-on-disk overhead is no longer required for thread
+attachment alone.
## How the skills pick a backend
-Every skill step that currently reads *"create a Gmail draft via
-`mcp__claude_ai_Gmail__create_draft`"* actually means *"create a draft
-via the project's preferred drafting backend, with `oauth_curl` always
-preferred when it is available"*.
-
-**Precedence — `oauth_curl` wins whenever it is configured**, regardless
-of what `tools.gmail.draft_backend` is set to. The point of having
-`oauth_curl` set up is `threadId` attachment; if the credentials are
-on disk, the skills should always use them. Resolution:
+Every skill step that says *"create a Gmail draft via
+`mcp__claude_ai_Gmail__create_draft`"* means *"create a draft via the
+project's configured drafting backend"*.
+
+**Default — `claude_ai_mcp` with `replyToMessageId`.** This is the
+recommended path. Resolution:
+
+1. **Resolve the latest message ID on the inbound thread.** Call
+ `mcp__claude_ai_Gmail__get_thread(threadId=<inbound>,
+ messageFormat='MINIMAL')` and take the `id` of the
+ chronologically-last message. The tracker stores `threadId` (per
+ the existing *security-thread* body field convention); the
+ message-ID resolution is one extra round-trip and the skills
+ absorb it.
+2. **Create the draft.** Call
+ `mcp__claude_ai_Gmail__create_draft(..., replyToMessageId=<that
+ message id>)`. The draft attaches to the inbound thread on the
+ sender's Gmail and surfaces in both the conversation view and the
+ global Drafts folder.
+3. **Fallback — omit `replyToMessageId`.** When the latest message
+ cannot be resolved (thread archived, deleted, or stale `threadId`),
+ create the draft with `replyToMessageId` omitted and rely on
+ subject-matched threading (`Re: <root subject>` plus the recipient's
+ own `In-Reply-To` / `References` chain). See
+ [`threading.md`](threading.md#fallback--subject-matched-draft-when-replytomessageid-is-unavailable).
+
+**Opt-in — `oauth_curl` for the cases the MCP cannot serve.** A user
+who has explicitly set `tools.gmail.draft_backend: oauth_curl` and
+who has a credentials file on disk:
1. **Probe for `oauth_curl` credentials** in this order:
- `tools.gmail.oauth_credentials_path` from
@@ -76,51 +99,32 @@ on disk, the skills should always use them. Resolution:
The probe is a single `test -f <path>` — actually parsing the file
or doing a token-refresh probe at this stage would burn HTTP
- round-trips on every draft and is wasted work; if the file exists,
- trust it and let the script's first call surface any auth failure
- with a clear error.
-2. **If credentials are found → use `oauth_curl`** unconditionally.
- Invoke
+ round-trips on every draft.
+2. **If credentials are found → use `oauth_curl`.** Invoke
`uv run --project <framework>/tools/gmail/oauth-draft oauth-draft-create`
with `--thread-id`, `--to`, `--cc`, `--subject`, `--body-file` —
see [`oauth-draft/README.md`](oauth-draft/README.md) for the full
shape.
- `threadId` attachment is guaranteed; the draft surfaces in both the
- conversation view (recipient-side threading) and — when no pile-up
- blocks it — the global Drafts folder. The user's
- `tools.gmail.draft_backend` setting is **ignored** in this branch.
-3. **If credentials are not found, fall back to `claude_ai_mcp`** —
- call `mcp__claude_ai_Gmail__create_draft`. `threadId` attachment is
- unavailable; the draft uses the subject-matched path documented in
- [`threading.md`](threading.md#fallback--subject-matched-draft-when-threadid-is-unavailable).
-4. **Hard explicit override**: a user who has oauth credentials on
- disk **but** wants to force `claude_ai_mcp` for a specific reason
- (e.g. the pile-up workaround in the next section) sets
- `tools.gmail.draft_backend: claude_ai_mcp_force` (note the
- `_force` suffix). The plain `claude_ai_mcp` value is treated as
- *"OK with either, prefer oauth_curl"* — it is the default, so a
- user who explicitly set it that way had no oauth set up at the
- time and the precedence rule covers them automatically once they
- add credentials. The `_force` suffix is the explicit *"never use
- oauth_curl"* signal.
+3. **If credentials are not found despite the user opting in →
+ fall back to `claude_ai_mcp` and surface the missing-credentials
+ warning.** Do not silently swallow the configuration mismatch.
The skills **surface which backend was used** in the proposal / recap
-so the user can tell at a glance whether the draft threads on their
-own Gmail view or only on the recipient's. The format is one line:
+so the user can tell at a glance how the draft is threaded. The format
+is one line:
+
+> *Draft created via `claude_ai_mcp` (replyToMessageId-attached to
+> message `<msg-id-prefix>...` on thread `<thread-id-prefix>...`)*
+
+or
> *Draft created via `oauth_curl` (threadId-attached on
> `<thread-id-prefix>...`)*
-or
+or, when fallback kicks in:
> *Draft created via `claude_ai_mcp` (subject-matched fallback —
-> `oauth_curl` credentials not found at default path; install via
-> `uv run --project <framework>/tools/gmail/oauth-draft oauth-draft-setup`
-> to get threadId attachment)*
-
-The fallback line is intentionally noisy when oauth credentials are
-absent — a user who would benefit from threadId attachment should
-see the install hint on every draft creation until they set it up.
+> `<reason: thread archived / latest message unresolved / etc.>`)*
## Detecting drafts that already exist on a thread
@@ -128,34 +132,28 @@ Before drafting a reply on a thread, skills check whether a pending
draft already exists so they do not silently shadow it (the claude.ai
MCP cannot update or delete drafts; see
[`operations.md`](operations.md#hard-limitation--no-update-no-delete)).
-The detection rule depends on which backend created the prior draft:
-
-- **`claude_ai_mcp` drafts** live as standalone server-side
- conversations on the user's Gmail. Detect them via
- `mcp__claude_ai_Gmail__list_drafts`, optionally narrowed by
- `query: "<recipient-email>"` or a distinctive subject substring.
- Each MCP-created draft surfaces as a separate top-level entry in
- the Drafts folder.
-- **`oauth_curl` drafts** attach to the inbound thread by `threadId`.
- They carry the `DRAFT` label but **may not surface in the global
- Drafts folder when multiple drafts pile up on the same thread**
- (see the *Known issue* section below). Detect them by reading the
- thread directly:
+Run **both** detection paths and treat any hit as *"a draft already
+exists; surface it to the user before drafting a new one"*:
+
+- **List drafts globally.** Call `mcp__claude_ai_Gmail__list_drafts`,
+ optionally narrowed by `query: "<recipient-email>"` or a
+ distinctive subject substring. Both `claude_ai_mcp`-with-
+ `replyToMessageId` drafts and `oauth_curl` drafts surface here, as
+ do legacy MCP drafts created without `replyToMessageId` (which live
+ as standalone server-side conversations).
+- **Read the thread directly.** Call
```text
mcp__claude_ai_Gmail__get_thread(threadId: "<inbound-thread-id>", messageFormat: MINIMAL)
```
- and scanning the returned messages for any whose `labelIds` (or
- the snippet's metadata) include `DRAFT`. Every `oauth_curl`-
- created draft on a thread is reachable this way regardless of
- pile-up. **`list_drafts` alone is not sufficient** when oauth
- credentials are configured — always do the per-thread check too.
+ and scan the returned messages for any whose `labelIds` (or the
+ snippet's metadata) include `DRAFT`. This catches thread-attached
+ drafts that — under the pile-up condition described below — may
+ not be navigable from the global Drafts folder.
-The composite rule: when a skill is about to draft a reply, run
-**both** detection paths (list_drafts + get_thread on the inbound
-threadId) and treat any hit as *"a draft already exists; surface it
-to the user before drafting a new one"*.
+`list_drafts` alone is not sufficient when thread-attached drafts
+are involved (either backend); always do the per-thread check too.
## Limitations that apply to both backends
@@ -170,10 +168,10 @@ to the user before drafting a new one"*.
Gmail account. The `oauth_curl` backend additionally requires the
user to manage a refresh token on disk; treat it like an SSH key.
-## Known issue — `oauth_curl` thread-attached drafts may not surface in the global Drafts folder
+## Known issue — thread-attached drafts may not surface in the global Drafts folder when stacked
Caught live on 2026-04-25 during the [`<tracker>#346`](https://github.com/<tracker>/issues/346)
-fix-skill flow: when **multiple `oauth_curl`-backed drafts pile up on
+fix-skill flow: when **multiple thread-attached drafts pile up on
the same Gmail thread** within a single skill flow (typical sequence:
security-cve-allocate drafts a CVE-allocated message → security-issue-sync
drafts a corrected version with updated state → security-issue-fix
@@ -185,77 +183,71 @@ view of the thread. The user's own report from that session:
*"Can't see the draft — I see some old drafts on the list but they
are missing"*.
-This appears to be a Gmail UI behaviour where multiple `threadId`-
-attached drafts on a single conversation collapse / hide in the
-global Drafts list rather than rendering as N separate entries. The
-drafts exist (a `gh api repos/.../drafts` round-trip confirms `DRAFT`
-labels and full message bodies); they are simply not navigable from
-the standard Drafts folder when stacked.
-
-The MCP-backed `claude_ai_mcp` path does not have this problem because
-each draft lives on its own server-side conversation (no `threadId`
-attachment), so each draft is a separate top-level entry in the
-Drafts folder.
+This is a Gmail UI behaviour where multiple thread-attached drafts on
+a single conversation collapse / hide in the global Drafts list
+rather than rendering as N separate entries. It applies to **both**
+backends — `claude_ai_mcp` drafts created with `replyToMessageId` and
+`oauth_curl` drafts attached by `threadId` — because both result in
+true thread-attached drafts on the Gmail server. The drafts exist
+(a Gmail API round-trip confirms `DRAFT` labels and full message
+bodies); they are simply not navigable from the standard Drafts
+folder when stacked.
+
+The only path that avoids this is creating a draft *without*
+attaching it to the inbound thread — the legacy MCP behaviour before
+`replyToMessageId` was added. Each such draft becomes its own
+top-level entry in the Drafts folder, at the cost of losing
+sender-side threading.
### Recommended workflow when re-drafting on a thread that already carries a pending draft
When a skill is about to draft a reply on a thread that **already
has a pending draft on it from an earlier skill pass in the same
-session**, prefer the `claude_ai_mcp` backend for the new draft —
-even when `tools.gmail.draft_backend` is set to `oauth_curl`. The
-trade-off:
+session**, omit the thread-attachment parameter for the new draft —
+i.e. call `mcp__claude_ai_Gmail__create_draft` *without*
+`replyToMessageId` (or `oauth-draft-create` *without* `--thread-id`).
+The trade-off:
- **Visibility wins:** the new draft is guaranteed to surface in the
user's Gmail Drafts folder, so they can actually see and review it.
- **Sender-side threading lost:** the new draft will start a new
- server-side thread on the user's own Gmail (Evan's mail client will
- still thread it onto the existing conversation via the
- `Re: <exact subject>` match, so the recipient experience is
- unaffected).
+ server-side thread on the user's own Gmail. The recipient's mail
+ client will still thread it onto the existing conversation via the
+ `Re: <exact subject>` match plus the `In-Reply-To` / `References`
+ headers Gmail synthesises, so the recipient experience is
+ unaffected.
The pile-up case is the only situation where this trade-off applies.
-For the **first** draft on a thread, `oauth_curl` remains the
-default — that draft is visible in both the conversation view and
-the Drafts folder.
+For the **first** draft on a thread, the default thread-attached path
+remains preferred — that draft is visible in both the conversation
+view and the Drafts folder.
### Concrete steps when the pile-up has already happened
-1. **Delete the stale `oauth_curl` drafts** via the Gmail API
+1. **Delete the stale drafts.** `oauth_curl` drafts can be deleted
+ via the Gmail API
(`DELETE https://gmail.googleapis.com/gmail/v1/users/me/drafts/<draft-id>`
with the OAuth bearer token from the same `oauth_curl` credentials
- file). Drafts created via `oauth_curl` are deletable via that same
- OAuth client; drafts created via the claude.ai MCP can only be
- discarded from the Gmail UI (the MCP is no-update / no-delete per
+ file). Drafts created via the claude.ai MCP can only be discarded
+ from the Gmail UI (the MCP is no-update / no-delete per
[`operations.md`](operations.md#hard-limitation--no-update-no-delete)).
-2. **Recreate the consolidated message via the claude.ai MCP** —
- `mcp__claude_ai_Gmail__create_draft` with the `Re: <exact subject>`
- line so it threads on the recipient's side via subject match.
+2. **Recreate the consolidated message.** Call
+ `mcp__claude_ai_Gmail__create_draft` with `replyToMessageId`
+ *omitted* and the `Re: <exact subject>` line so the recipient's
+ client still threads it via subject match.
3. **Surface the path change in the tracker's status rollup**
- so the audit trail shows why the draft moved from `oauth_curl`
- to `claude_ai_mcp` — a future triager looking at the rollup
- should see *"draft re-routed to claude_ai_mcp because oauth_curl
- pile-up was hidden from the Drafts folder"* rather than wondering
- why the threading suddenly degraded.
+ so the audit trail shows why this draft is not thread-attached.
+ A future triager looking at the rollup should see *"draft created
+ without `replyToMessageId` because the thread already carried a
+ pending pile-up"* rather than wondering why the threading
+ suddenly degraded.
### When this rule does not apply
-- **The thread has no pending draft yet** — keep using `oauth_curl`
- (per the user's `draft_backend` config). This is the single-draft
- case and the visibility issue does not trigger.
-- **The user is configured for `claude_ai_mcp` to begin with** —
- no change. Subject-matched threading is the default for that
- backend; the recommendation above is specifically for `oauth_curl`
- users who hit a pile-up.
-
-## Migration — when the claude.ai MCP adds `threadId`
-
-If a future version of the claude.ai Gmail MCP accepts `threadId` on
-`create_draft`, this backend split can retire. The probe that checks
-for this — see the scheduled routine under
-[`/schedule`](../../README.md#scheduled-routines) named
-`gmail-mcp-threadid-probe` — runs monthly. When it detects the new
-parameter, it comments on a tracking issue so we can swap the default
-back to `claude_ai_mcp` and deprecate this directory.
+- **The thread has no pending draft yet** — keep the default
+ thread-attached path (`replyToMessageId` for `claude_ai_mcp`,
+ `--thread-id` for `oauth_curl`). The single-draft case does not
+ trigger the visibility issue.
## Referenced by
diff --git a/tools/gmail/oauth-draft/README.md b/tools/gmail/oauth-draft/README.md
index f930926..5604ca6 100644
--- a/tools/gmail/oauth-draft/README.md
+++ b/tools/gmail/oauth-draft/README.md
@@ -38,14 +38,13 @@ user-provided OAuth refresh token. Three console scripts:
| Console script | Purpose |
|---|---|
| `oauth-draft-setup` | One-time interactive OAuth consent flow that writes the credentials JSON. |
-| `oauth-draft-create` | Create a Gmail draft with **`threadId` attachment** (the claude.ai Gmail MCP cannot do this). |
-| `oauth-draft-mark-read` | Bulk-modify Gmail threads matching a search query (default: mark as read by removing the `UNREAD` label). |
-
-The behavioural contract for the `oauth_curl` drafting backend and
-the surrounding policy live in
-[`../draft-backends.md`](../draft-backends.md). This README covers
-local-setup, day-to-day invocation, and the project's own
-test/lint workflow.
+| `oauth-draft-create` | Create a Gmail draft with `threadId` attachment. (As of the `replyToMessageId` parameter on the claude.ai Gmail MCP `create_draft`, the MCP can also produce thread-attached drafts — see [`../draft-backends.md`](../draft-backends.md). This script remains useful when you have a `threadId` on hand and would rather skip the extra `get_thread` round-trip the MCP path requires, and is the only path that lets the skills delete drafts via the Gmail API afterwards.) |
+| `oauth-draft-mark-read` | Bulk-modify Gmail threads matching a search query (default: mark as read by removing the `UNREAD` label). No MCP equivalent today. |
+
+The default and recommended drafting backend is the claude.ai Gmail
+MCP — see [`../draft-backends.md`](../draft-backends.md) for when to
+opt into `oauth_curl`. This README covers local-setup, day-to-day
+invocation, and the project's own test/lint workflow.
## Run
diff --git a/tools/gmail/operations.md b/tools/gmail/operations.md
index 2252d1d..59b682d 100644
--- a/tools/gmail/operations.md
+++ b/tools/gmail/operations.md
@@ -104,42 +104,58 @@ in `.apache-steward-overrides/user.md` under
in [`draft-backends.md`](draft-backends.md); the call shape per
backend is here.
-| Backend | Value | `threadId` attach? |
+| Backend | Value | Thread attach? |
|---|---|---|
-| claude.ai Gmail MCP | `claude_ai_mcp` (default) | **no** (see below) |
-| OAuth + `curl` | `oauth_curl` | **yes** |
+| claude.ai Gmail MCP | `claude_ai_mcp` (default) | **yes** — via `replyToMessageId` |
+| OAuth + `curl` | `oauth_curl` | **yes** — via `threadId` |
### Create draft — `claude_ai_mcp` backend
-The claude.ai Gmail MCP's `create_draft` tool does **not** accept a
-`threadId` parameter. The Gmail REST API supports it on
-`drafts.create`, but the MCP does not plumb it through. Drafts
-created via this backend always start a new conversation on the
-**sender's** Gmail side; recipients' mail clients thread-attach via
-subject + `In-Reply-To` / `References` matching, which usually works
-but is not guaranteed.
+The claude.ai Gmail MCP's `create_draft` tool accepts a
+`replyToMessageId` parameter (a Gmail *message* ID, not a thread ID).
+When supplied, Gmail attaches the draft to the conversation that
+contains that message — server-side, on the sender's Gmail. The new
+draft is visible in both the conversation view and the global Drafts
+folder, and the original message body is appended to the draft's body
+(standard "reply" composition). Recipients' mail clients thread-attach
+via the subject + `In-Reply-To` / `References` headers Gmail synthesises
+from the parent message.
```text
+# 1. Resolve the message to reply to. The skills always reply to the
+# chronologically-last message on the inbound thread (see
+# threading.md):
+mcp__claude_ai_Gmail__get_thread(
+ threadId='<inbound-threadId>',
+ messageFormat='MINIMAL',
+)
+# → take messages[-1].id as <reply-to-message-id>
+
+# 2. Create the draft with replyToMessageId set:
mcp__claude_ai_Gmail__create_draft(
subject='Re: <root subject of the inbound message>',
to=['<primary>'],
cc=['<security-list>', ...],
body='<body>',
+ replyToMessageId='<reply-to-message-id>',
)
```
+- **`replyToMessageId` is the message ID of the latest message on the
+ inbound thread.** Resolve it from `get_thread` rather than guessing
+ — Gmail does not accept a `threadId` here.
- **Subject is always `Re: <root subject>`**, never fabricated. A
- drifted subject defeats subject-based threading on every client.
+ drifted subject defeats subject-based threading on every client and
+ is a separate signal Gmail's UI uses to render the conversation
+ header.
- **Never send.** The skills only *create* drafts; a human
review-and-send step is required before every outbound message.
-- **Subject-fallback threading is the only path.** See the
- [fallback rule](threading.md#fallback--subject-matched-draft-when-threadid-is-unavailable)
+- **Fallback** — when the inbound `threadId` cannot be resolved or
+ the latest message is not retrievable, omit `replyToMessageId` and
+ let the draft thread by subject only. See the
+ [fallback rule](threading.md#fallback--subject-matched-draft-when-replytomessageid-is-unavailable)
in `threading.md` for when this applies and when it does not.
-When the user needs `threadId`-attached drafts (so the draft threads
-on their own Gmail view and the drafts queue stays in lock-step with
-the inbound thread), switch the backend to `oauth_curl` — see below.
-
### Create draft — `oauth_curl` backend
The `oauth-draft-create` console script (in
diff --git a/tools/gmail/threading.md b/tools/gmail/threading.md
index 34092da..104e948 100644
--- a/tools/gmail/threading.md
+++ b/tools/gmail/threading.md
@@ -4,7 +4,7 @@
- [Gmail — drafts stay on the inbound thread](#gmail--drafts-stay-on-the-inbound-thread)
- [The rule](#the-rule)
- - [Fallback — subject-matched draft when `threadId` is unavailable](#fallback--subject-matched-draft-when-threadid-is-unavailable)
+ - [Fallback — subject-matched draft when `replyToMessageId` is unavailable](#fallback--subject-matched-draft-when-replytomessageid-is-unavailable)
- [Special case — ASF-security relay](#special-case--asf-security-relay)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -16,30 +16,32 @@
Every drafted email that relates to a tracking issue **should**
attach to the original inbound Gmail thread — the thread whose
-`threadId` was recorded when the tracker was imported. The **Gmail
-API** threads most reliably when a draft carries a `threadId`;
+`threadId` was recorded when the tracker was imported. Gmail's
+server-side threader attaches by message-ID-of-parent (passed as
+`replyToMessageId` on the MCP, or by `threadId` on the OAuth path);
**other mail clients** (Thunderbird, Outlook, Apple Mail, the
-recipient's own client) commonly fall back to subject-based
-threading via the MIME `In-Reply-To` / `References` headers and the
-subject line.
+recipient's own client) thread by the MIME `In-Reply-To` /
+`References` headers and the subject line, which Gmail synthesises
+from the parent message in either case.
-Whether `threadId` is actually available to the skills depends on
-the drafting backend the user has configured — see
+Both supported drafting backends now provide thread-attachment — see
[`draft-backends.md`](draft-backends.md):
-| Backend | `threadId` attach | Subject fallback |
+| Backend | Thread attach | Mechanism |
|---|---|---|
-| `oauth_curl` (opt-in) | **yes** — guaranteed | n/a (always attaches) |
-| `claude_ai_mcp` (default) | **no** — the MCP does not plumb it through | always |
+| `claude_ai_mcp` (default) | **yes** | `replyToMessageId` — the message ID of the chronologically-last message on the inbound thread |
+| `oauth_curl` (opt-in) | **yes** | `threadId` plus explicit `In-Reply-To` / `References` headers |
The two threading paths available to the skills, in preferred order:
-1. **`threadId`-attached draft** — the first-choice path. Requires
- the `oauth_curl` backend. Use whenever the inbound `threadId` is
- known and the user has configured that backend.
-2. **Subject-matched draft** — the pragmatic fallback. The only
- path on the `claude_ai_mcp` backend; also the fallback on
- `oauth_curl` when the `threadId` cannot be resolved.
+1. **Thread-attached draft** — the first-choice path. Both backends
+ support this. Resolve the inbound thread's latest message ID (via
+ `get_thread`) and pass it to `replyToMessageId`, or pass the
+ `threadId` to `oauth-draft-create --thread-id`.
+2. **Subject-matched draft** — the pragmatic fallback. Use when the
+ thread cannot be resolved (archived, deleted, stale `threadId`)
+ or the inbound subject is unsafe to match on. Both backends fall
+ back to this by simply omitting the thread-attachment parameter.
The call shape (signature, kwargs, no-send rule) per backend lives in
[`operations.md` — Drafting backends](operations.md#drafting-backends);
@@ -71,52 +73,51 @@ like live here.
overlap; it requires `threadId` or (as the fallback) a matching
subject plus the right `In-Reply-To` / `References` headers.
-## Fallback — subject-matched draft when `threadId` is unavailable
+## Fallback — subject-matched draft when `replyToMessageId` is unavailable
-`threadId` is the first-choice path, but the skills must also work
-in cases where it cannot be resolved or the backend does not
-support it:
+Thread attachment is the first-choice path, but the skills must also
+work in cases where the inbound thread cannot be resolved:
-- **The user has `tools.gmail.draft_backend: claude_ai_mcp`** (the
- default). The claude.ai Gmail MCP does not accept `threadId` on
- `create_draft`; every draft created via this backend uses the
- subject-matched path. See [`draft-backends.md`](draft-backends.md)
- for the one-time switch to the `oauth_curl` backend.
- The tracker's *security-thread* body field was never filled in
(see
[`../github/issue-template.md`](../github/issue-template.md#field-roles-the-skills-use)
for the field role).
- The `threadId` in that field is stale (the thread was deleted
or archived out of the user's Gmail search index).
+- `get_thread` returns no messages (the thread exists but has been
+ emptied), so there is no `replyToMessageId` to point at.
- The draft is a brand-new outbound ask on a topic the inbound
thread did not cover (e.g. a relay request to a PMC member who
was not on the original thread), where re-threading on the
original inbound is actually confusing.
- The Gmail backend returns an error when attaching the supplied
- `threadId` (rare, but possible if the user has moved the thread
- between accounts).
-
-In these cases, **create the draft with `threadId` omitted but with
-the matching subject line from the inbound message**. Gmail will
-start a new conversation on the sender's side, but most other
-clients (and Gmail's own subject-fallback behaviour on the
-recipient's side) will still thread the reply by subject. This is
-not as good as a `threadId`-attached draft, but it is substantially
-better than either fabricating a new subject or not drafting at
-all.
+ message / thread (rare, but possible if the user has moved the
+ thread between accounts).
+- A draft already exists on the same thread and the pile-up
+ workaround in [`draft-backends.md`](draft-backends.md#known-issue--thread-attached-drafts-may-not-surface-in-the-global-drafts-folder-when-stacked)
+ applies — drop thread attachment for the new draft so it surfaces
+ in the global Drafts folder.
+
+In these cases, **create the draft with `replyToMessageId` omitted
+(or `--thread-id` omitted on the OAuth path) but with the matching
+subject line from the inbound message**. Gmail will start a new
+conversation on the sender's side, but most other clients (and
+Gmail's own subject-fallback behaviour on the recipient's side) will
+still thread the reply by subject. This is not as good as a
+thread-attached draft, but it is substantially better than either
+fabricating a new subject or not drafting at all.
**Surface the degraded threading in the skill's proposal** so the
user knows which path the draft took:
+- *"Draft attached by `replyToMessageId` to message `<msg-id-prefix>...`
+ on thread `<thread-id-prefix>...`."* — the good case (default
+ `claude_ai_mcp` backend).
- *"Draft attached by `threadId` (via `oauth_curl` backend)."* —
- the good case.
-- *"Draft created by subject fallback (via `claude_ai_mcp` backend —
- `threadId` not supported). Gmail shows it as a new conversation
- server-side; the recipient's client will most likely thread it via
- the `Re: <subject>` match."* — the default-backend case.
-- *"Draft created by subject fallback (`threadId` was unavailable
- because `<reason>`)."* — `oauth_curl` backend but `threadId`
- missing for some other reason.
+ the good case for the OAuth-opt-in user.
+- *"Draft created by subject fallback (`<reason>`). Gmail shows it
+ as a new conversation server-side; the recipient's client will
+ thread it via the `Re: <subject>` match."*
When the fallback kicks in, record the reason on the tracker's
status comment so the next sync run can see why a new Gmail thread
@@ -126,11 +127,11 @@ of the conversation the reporter sees.
**When fallback is not appropriate.** Some cases genuinely warrant
stopping rather than drafting on a mismatched subject. Examples:
-- You have neither a `threadId` **nor** a matching subject to use
- (typically when the tracker has never been linked to any inbound
- thread at all — a bug, usually a missed import step). Stop and
- surface it; drafting with no thread context at all is worse than
- no draft.
+- You have neither a thread to attach to **nor** a matching subject
+ to use (typically when the tracker has never been linked to any
+ inbound thread at all — a bug, usually a missed import step).
+ Stop and surface it; drafting with no thread context at all is
+ worse than no draft.
- The inbound subject itself is the reason you cannot thread (the
reporter sent the report with an empty subject, a generic
*"Security"*, or a subject that collides with dozens of unrelated
@@ -143,6 +144,7 @@ stopping rather than drafting on a mismatched subject. Examples:
When the inbound report arrives via an ASF forwarder rather than
directly from the external reporter, the drafting shape changes
slightly (different `To:` / `Cc:`, relay-specific body language) but
-the threading rules above are **unchanged**: prefer `threadId`;
-fall back to the inbound subject when it is not available. See
-[`asf-relay.md`](asf-relay.md).
+the threading rules above are **unchanged**: resolve and attach to
+the inbound thread (`replyToMessageId` on the default backend,
+`threadId` on `oauth_curl`); fall back to the inbound subject when
+the thread cannot be resolved. See [`asf-relay.md`](asf-relay.md).
diff --git a/tools/gmail/tool.md b/tools/gmail/tool.md
index 1067049..0c16687 100644
--- a/tools/gmail/tool.md
+++ b/tools/gmail/tool.md
@@ -31,8 +31,8 @@ file in this directory:
| Capability | File | What it covers |
|---|---|---|
| MCP operations | [`operations.md`](operations.md) | The `mcp__claude_ai_Gmail__*` tool catalogue (search, read, draft, list) + the no-update / no-delete limitation |
-| Drafting backends | [`draft-backends.md`](draft-backends.md) | The two drafting backends (claude.ai Gmail MCP vs OAuth + `curl`), why both exist, and the `tools.gmail.draft_backend` config knob |
-| Threading | [`threading.md`](threading.md) | The *"always pass `threadId` when the backend supports it"* rule — how drafts stay on the inbound thread across reporter replies, ASF-security relays, PMC credit questions, follow-ups |
+| Drafting backends | [`draft-backends.md`](draft-backends.md) | The two drafting backends (claude.ai Gmail MCP — default and recommended, with thread attachment via `replyToMessageId`; OAuth + `curl` — opt-in for bulk operations and `threadId`-keyed drafts), why both exist, and the `tools.gmail.draft_backend` config knob |
+| Threading | [`threading.md`](threading.md) | The *"always attach the draft to the inbound thread when possible"* rule — how drafts stay on the inbound thread across reporter replies, ASF-security relays, PMC credit questions, follow-ups |
| ASF-security-relay drafting | [`asf-relay.md`](asf-relay.md) | Special-case drafting rules when the inbound report is relayed by the ASF security team rather than sent by the external reporter directly |
| Search queries | [`search-queries.md`](search-queries.md) | Gmail search-operator cheat-sheet + skill-specific query templates (candidate-listing, reporter-thread lookup, CVE-review comments) |
@@ -79,19 +79,21 @@ on is:
thread IDs.
2. **Read** — given a thread ID, return the full message history.
3. **Draft** — given a thread ID, create an unsent reply on the
- inbound thread with thread attachment **where the backend
- supports it**; otherwise fall back to a subject-matched draft
- (`Re: <root subject>` + `In-Reply-To` / `References` headers so
- the recipient's client still threads it). The two backends
- available today are documented in
- [`draft-backends.md`](draft-backends.md).
+ inbound thread with thread attachment (the default
+ `claude_ai_mcp` backend resolves the thread's latest message ID
+ and attaches via `replyToMessageId`; the opt-in `oauth_curl`
+ backend attaches by `threadId`); fall back to a subject-matched
+ draft (`Re: <root subject>` + `In-Reply-To` / `References`
+ headers so the recipient's client still threads it) when the
+ thread cannot be resolved. The two backends available today are
+ documented in [`draft-backends.md`](draft-backends.md).
4. **List drafts** — so stale drafts can be detected before the
skills forward-flag them in every new sync comment.
-The threading semantics — *"prefer thread attachment when
-available; fall back to same-subject matching, never fabricate a
-new subject"* — are non-negotiable regardless of backend; see
-[`threading.md`](threading.md).
+The threading semantics — *"attach the draft to the inbound thread
+when possible; fall back to same-subject matching when not, never
+fabricate a new subject"* — are non-negotiable regardless of
+backend; see [`threading.md`](threading.md).
## Confidentiality