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