gogcli-mcp 4.3.0 → 4.4.0

package/src/tools/gmail.ts

@@ -5,8 +5,9 @@ import { finalizeGmailSearch, fetchGmailPages } from '../gmail-results.js';
 import type { GogArg } from '../runner.js';
 import { attachInlineParam, inlineAttachmentArgs } from '../attachments.js';
 import type { InlineAttachmentInput } from '../attachments.js';
-import { attachmentNames, bodyPreview, extractEmails, logGmailDispatch, replyDispatchOp, requireGmailDispatchConfirmation, resultText } from '../gmail-dispatch-guard.js';
+import { attachmentDetails, attachmentNames, attachmentPreview, bodyPreview, CONFIRM_FALLBACK_DESCRIPTION, confirmTokenParam, extractEmails, logGmailDispatch, replyDispatchOp, requireGmailDispatchConfirmation, resultText, senderPreview } from '../gmail-dispatch-guard.js';
 import { pos } from '../argv.js';
+import { hasCommandWord } from '../dispatch-confirmation.js';
 import { confinePath, confinePaths } from '../file-roots.js';
 
 // gmail reply / reply-all share an identical flag set (gog 0.27+); they differ
@@ -98,8 +99,9 @@ export function appendReplyFlags(args: GogArg[], f: ReplyFlags): void {
 // The send-side reply/reply-all schema, distinct from the shared replySchema
 // above. gog_gmail_drafts_reply / _reply_all (gogcli-mcp-gmail) reuse
 // replySchema verbatim and must never gain a send-confirmation input — draft
-// tools stage mail, while send tools request confirmation through MCP.
-const sendReplySchema = z.object(replySchema);
+// tools stage mail, while send tools request confirmation (through MCP, or the
+// opt-in confirmToken fallback, which is why only THIS schema carries it).
+const sendReplySchema = z.object({ ...replySchema, confirmToken: confirmTokenParam });
 
 // gog's own `reply`/`reply-all` response never echoes the resolved
 // recipients when replying to a single message (the common case: gog only
@@ -148,6 +150,62 @@ export function computeReplyRecipients(
   return emails;
 }
 
+/** `message.threadId` out of `gog gmail get --format=metadata --json`, if present. */
+export function metadataThreadId(raw: string): string | undefined {
+  try {
+    const threadId = (JSON.parse(raw) as { message?: { threadId?: unknown } } | null)?.message?.threadId;
+    return typeof threadId === 'string' ? threadId : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// The token fallback's preview and bound payload for a reply. To/Cc/Bcc are the
+// same approximation computeReplyRecipients makes (gog composes the final list),
+// split by field so the user can see who is on Bcc.
+function replyTokenSubject(
+  kind: 'reply' | 'reply-all',
+  messageId: string,
+  account: string | undefined,
+  headers: Record<string, string>,
+  threadId: string | undefined,
+  flags: ReplyFlags,
+) {
+  const removed = new Set(extractEmails(...(flags.remove ?? [])));
+  const keep = (emails: string[]) => emails.filter((e) => !removed.has(e));
+  const to = keep(extractEmails(headers.from, ...(kind === 'reply-all' ? [headers.to] : []), ...(flags.to ?? [])));
+  const cc = keep(extractEmails(...(kind === 'reply-all' ? [headers.cc] : []), ...(flags.cc ?? [])));
+  const bcc = keep(extractEmails(...(flags.bcc ?? [])));
+  const attachments = attachmentDetails(flags.attach, flags.attachInline);
+  const subject = flags.subject || (headers.subject ? `Re: ${headers.subject}` : undefined);
+  const from = flags.from ?? (flags.autoFromAddressedAlias ? 'the send-as alias the original was addressed to' : senderPreview(account));
+  const localFiles = attachmentDetails([flags.bodyHtmlFile, flags.signatureFile].filter((p): p is string => Boolean(p)), undefined);
+  return {
+    target: messageId,
+    payload: {
+      kind, to, cc, bcc, subject, from,
+      body: flags.body, bodyHtml: flags.bodyHtml, localFiles,
+      signature: Boolean(flags.signature), signatureFrom: flags.signatureFrom,
+      attachments, quote: !flags.noQuote,
+      threadId, inReplyTo: headers.message_id, references: headers.references,
+    },
+    preview: {
+      from, to, cc, bcc, subject,
+      body: flags.body,
+      ...(flags.bodyHtml ? { bodyHtml: flags.bodyHtml } : {}),
+      ...(flags.bodyHtmlFile ? { bodyHtmlFile: flags.bodyHtmlFile } : {}),
+      ...(flags.signature || flags.signatureFrom || flags.signatureFile
+        ? { signature: flags.signatureFile ?? flags.signatureFrom ?? 'the Gmail signature of the sending address' }
+        : {}),
+      quotesOriginal: !flags.noQuote,
+      attachments: attachmentPreview(attachments),
+      replyingToMessageId: messageId,
+      threadId,
+      inReplyTo: headers.message_id,
+    },
+  };
+}
+
 // Shared by gog_gmail_reply and gog_gmail_reply_all: fetch the target
 // message's headers (always — the prompt needs them and so does the audit
 // log on the accepted path), then confirm and send.
@@ -161,12 +219,14 @@ async function sendReply(
   account: string | undefined,
   flags: ReplyFlags,
   ctx: ServerContext,
+  confirmToken?: string,
 ) {
   const metaResult = await runOrDiagnose(['gmail', 'get', pos(messageId), '--format=metadata'], { account });
   if (metaResult.isError) return metaResult;
-  const headers = parseMetadataHeaders(resultText(metaResult));
+  const metaText = resultText(metaResult);
+  const headers = parseMetadataHeaders(metaText);
   const recipients = computeReplyRecipients(kind, headers, flags);
-  const confirmation = requireGmailDispatchConfirmation(ctx, replyDispatchOp(kind), {
+  const confirmation = await requireGmailDispatchConfirmation(ctx, replyDispatchOp(kind), {
     messageId,
     recipients,
     recipientCount: recipients.length,
@@ -177,6 +237,13 @@ async function sendReply(
     bodyHtmlFile: flags.bodyHtmlFile,
     attachmentCount: (flags.attach?.length ?? 0) + (flags.attachInline?.length ?? 0),
     attachments: attachmentNames(flags.attach, flags.attachInline),
+  }, {
+    tool: toolName,
+    account,
+    confirmToken,
+    // The metadata read above IS the phase-2 re-read: it runs on every call,
+    // so the original's Message-ID/References are fresh here.
+    subject: () => replyTokenSubject(kind, messageId, account, headers, metadataThreadId(metaText), flags),
   });
   if (confirmation) return confirmation;
   const args: GogArg[] = ['gmail', kind, pos(messageId)];
@@ -205,12 +272,11 @@ export function vetGmailRun(subcommand: string, args: readonly string[]): string
     return `gog gmail ${subcommand} can forward or hand over mail and is not available through gog_gmail_run. Use the dedicated gog_gmail_* tool instead.`;
   }
   if (subcommand === 'settings') {
-    // kong lets flags precede the command word, and a global flag can take its
-    // value as the next token (`settings --color never filters ...`), so the
-    // word is not necessarily args[0]. Refuse it wherever it appears; a
-    // legitimate settings call carrying one of these words as a value is rare
-    // and has a dedicated tool anyway.
-    const blocked = args.find((a) => GMAIL_RUN_BLOCKED_SETTINGS.has(a.toLowerCase()));
+    // A global flag can take its value as the next token (`settings --color
+    // never filters ...`), so the word is not necessarily args[0]. Refuse it
+    // wherever it appears; a legitimate settings call carrying one of these
+    // words as a value is rare and has a dedicated tool anyway.
+    const blocked = hasCommandWord(args, GMAIL_RUN_BLOCKED_SETTINGS);
     if (blocked) {
       return `gog gmail settings ${blocked} can forward or hand over mail and is not available through gog_gmail_run. Use the dedicated gog_gmail_* tool instead.`;
     }
@@ -291,7 +357,8 @@ export function registerGmailTools(server: McpServer): void {
       + 'and byte sizes — check it to confirm the files were embedded. '
       + 'NOT the tool for answering a message: replyToMessageId only files this in the right thread — the '
       + 'subject, recipients and body are entirely yours, and the original is not quoted unless you set '
-      + 'quote. Use gog_gmail_reply / gog_gmail_reply_all instead, which inherit all three.',
+      + 'quote. Use gog_gmail_reply / gog_gmail_reply_all instead, which inherit all three.'
+      + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       to: z.string().describe('Recipient(s), comma-separated'),
@@ -305,8 +372,9 @@ export function registerGmailTools(server: McpServer): void {
       attach: z.array(z.string()).optional().describe('File paths to attach (repeatable), resolved ON THE GOG SERVER\'s filesystem — NOT this client\'s. Only usable when gog runs on the same machine you do (local stdio); on a hosted deployment (e.g. mcp-host) these paths do not exist and the call fails with "no such file or directory" — use attachInline there. Each file is read on the server, base64-encoded with a MIME type inferred from its extension, and added as a multipart attachment. Must be inside the server\'s GOG_FILE_ROOTS directories (default ~/gogcli-mcp-files).'),
       attachInline: attachInlineParam,
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ to, subject, body, cc, bcc, replyToMessageId, threadId, quote, attach, attachInline, account }, ctx) => {
+  }, async ({ to, subject, body, cc, bcc, replyToMessageId, threadId, quote, attach, attachInline, account, confirmToken }, ctx) => {
     confinePaths(attach, 'attach');
     // Built (and validated — inlineAttachmentArgs throws on bad base64 or an
     // oversize file) BEFORE the confirmation request, on both paths: a prompt that
@@ -334,7 +402,7 @@ export function registerGmailTools(server: McpServer): void {
     args.push(...inline);
 
     const recipients = extractEmails(to, cc, bcc);
-    const confirmation = requireGmailDispatchConfirmation(ctx, 'gmail.send', {
+    const confirmation = await requireGmailDispatchConfirmation(ctx, 'gmail.send', {
       to, cc, bcc, recipients, recipientCount: recipients.length, subject,
       bodyLength: body.length,
       bodyPreview: bodyPreview(body),
@@ -342,6 +410,27 @@ export function registerGmailTools(server: McpServer): void {
       quoting: Boolean(quote),
       attachmentCount: (attach?.length ?? 0) + (attachInline?.length ?? 0),
       attachments: attachmentNames(attach, attachInline),
+    }, {
+      tool: 'gog_gmail_send',
+      account,
+      confirmToken,
+      // Nothing is stored between the phases: the payload IS the arguments,
+      // so phase 2 must repeat them and any difference is a changed send.
+      subject: () => {
+        const attachments = attachmentDetails(attach, attachInline);
+        const from = senderPreview(account);
+        return {
+          target: replyToMessageId ?? threadId ?? '',
+          payload: { from, to, cc, bcc, subject, body, attachments, threadId, inReplyTo: replyToMessageId, quote: Boolean(quote) },
+          preview: {
+            from, to, cc, bcc, subject, body,
+            attachments: attachmentPreview(attachments),
+            threadId,
+            inReplyTo: replyToMessageId,
+            quotesOriginal: Boolean(quote),
+          },
+        };
+      },
     });
     if (confirmation) return confirmation;
     const result = await runOrDiagnose(args, { account });
@@ -376,13 +465,14 @@ export function registerGmailTools(server: McpServer): void {
       + 'brand-new message, with the original nowhere in it. To answer every participant use gog_gmail_reply_all. '
       + 'The gogcli-mcp-gmail package adds two more routes with the same composition: gog_gmail_autoreply to reply '
       + 'across every message matching a query, and gog_gmail_drafts_reply to stage this exact reply as a draft '
-      + 'instead of sending it.',
+      + 'instead of sending it.'
+      + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: sendReplySchema,
-  }, async ({ messageId, account, ...flags }, ctx) => {
+  }, async ({ messageId, account, confirmToken, ...flags }, ctx) => {
     assertNotBoth('bodyHtml', 'bodyHtmlFile', flags.bodyHtml, flags.bodyHtmlFile);
     confineReplyPaths(flags);
-    return sendReply('reply', 'gog_gmail_reply', messageId, account, flags, ctx);
+    return sendReply('reply', 'gog_gmail_reply', messageId, account, flags, ctx, confirmToken);
   });
 
   server.registerTool('gog_gmail_reply_all', {
@@ -393,13 +483,14 @@ export function registerGmailTools(server: McpServer): void {
       + 'confirmation. '
       + 'Reply to all participants of a Gmail message (the sender plus every To/Cc recipient). Same inherited "Re:" '
       + 'subject and quoted original as gog_gmail_reply. Use the remove flag to drop specific recipients from the '
-      + 'reply-all.',
+      + 'reply-all.'
+      + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: sendReplySchema,
-  }, async ({ messageId, account, ...flags }, ctx) => {
+  }, async ({ messageId, account, confirmToken, ...flags }, ctx) => {
     assertNotBoth('bodyHtml', 'bodyHtmlFile', flags.bodyHtml, flags.bodyHtmlFile);
     confineReplyPaths(flags);
-    return sendReply('reply-all', 'gog_gmail_reply_all', messageId, account, flags, ctx);
+    return sendReply('reply-all', 'gog_gmail_reply_all', messageId, account, flags, ctx, confirmToken);
   });
 
   registerRunTool(server, {

package/tests/gmail-dispatch-guard.test.ts

@@ -1,18 +1,26 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { rawTextResult } from '@chrischall/mcp-utils';
 import type { CallToolResult, ServerContext } from '@modelcontextprotocol/server';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resetConfirmTokenState } from '../src/send-confirm-token.js';
 import {
   GMAIL_DISPATCH_OPS,
   BODY_PREVIEW_MAX,
+  CONFIRM_INSTRUCTION,
+  attachmentDetails,
+  attachmentPreview,
   attachmentNames,
   bodyPreview,
+  senderPreview,
   extractEmails,
   logGmailDispatch,
   replyDispatchOp,
   requireGmailDispatchConfirmation,
   resultText,
 } from '../src/gmail-dispatch-guard.js';
-import type { GmailDispatchOp } from '../src/gmail-dispatch-guard.js';
+import type { DispatchTokenFallback, GmailDispatchOp, TokenSubject } from '../src/gmail-dispatch-guard.js';
 
 describe('extractEmails', () => {
   it('extracts a bare address', () => {
@@ -159,8 +167,8 @@ function ctxDeclaring(capabilities: unknown): ServerContext {
 /** claude.ai's measured shape: extensions and nothing else. */
 const CANNOT_BE_ASKED = ctxDeclaring({ extensions: {} });
 
-function refusalNote(op: GmailDispatchOp): string {
-  const result = requireGmailDispatchConfirmation(CANNOT_BE_ASKED, op, {}) as CallToolResult;
+async function refusalNote(op: GmailDispatchOp): Promise<string> {
+  const result = await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, op, {}) as CallToolResult;
   return JSON.parse(resultText(result)).note as string;
 }
 
@@ -185,8 +193,8 @@ const EXPECTED_TWIN: Record<GmailDispatchOp, string | null> = {
 describe('requireGmailDispatchConfirmation on a client that cannot be asked', () => {
   it.each(GMAIL_DISPATCH_OPS.map((op) => [op, EXPECTED_TWIN[op]] as const))(
     'answers %s with its staging twin %s',
-    (op, twin) => {
-      const note = refusalNote(op);
+    async (op, twin) => {
+      const note = await refusalNote(op);
       expect(note).toContain('cannot show a confirmation prompt');
       if (twin === null) {
         // A bulk auto-reply over a search has no draft twin, and naming a tool
@@ -207,20 +215,20 @@ describe('requireGmailDispatchConfirmation on a client that cannot be asked', ()
   it.each([
     ['reply', 'gog_gmail_drafts_reply'],
     ['reply-all', 'gog_gmail_drafts_reply_all'],
-  ] as const)('derives the %s op from the real call path', (kind, twin) => {
-    expect(refusalNote(replyDispatchOp(kind))).toContain(`Stage it with ${twin} instead`);
+  ] as const)('derives the %s op from the real call path', async (kind, twin) => {
+    expect(await refusalNote(replyDispatchOp(kind))).toContain(`Stage it with ${twin} instead`);
   });
 
   // Every staging twin used to point at gog_gmail_drafts_send, which now asks
   // for confirmation too — so on a client that cannot be asked, the way through
   // is the user sending the saved draft from Gmail themselves.
-  it('tells a client that cannot be asked that the user sends the staged draft from Gmail', () => {
-    expect(refusalNote('gmail.send')).toMatch(/send it from Gmail/);
-    expect(refusalNote('gmail.drafts-send')).toMatch(/still saved.*send it from Gmail/);
+  it('tells a client that cannot be asked that the user sends the staged draft from Gmail', async () => {
+    expect(await refusalNote('gmail.send')).toMatch(/send it from Gmail/);
+    expect(await refusalNote('gmail.drafts-send')).toMatch(/still saved.*send it from Gmail/);
   });
 
-  it('refuses rather than dispatching, and says so in the payload', () => {
-    const result = requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.forward', {
+  it('refuses rather than dispatching, and says so in the payload', async () => {
+    const result = await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.forward', {
       messageId: 'm1',
       to: 'someone@example.com',
     }) as CallToolResult;
@@ -233,8 +241,8 @@ describe('requireGmailDispatchConfirmation on a client that cannot be asked', ()
     });
   });
 
-  it('still asks a client that declares form elicitation', () => {
-    expect(requireGmailDispatchConfirmation(ctxDeclaring({ elicitation: { form: {} } }), 'gmail.forward', {}))
+  it('still asks a client that declares form elicitation', async () => {
+    expect(await requireGmailDispatchConfirmation(ctxDeclaring({ elicitation: { form: {} } }), 'gmail.forward', {}))
       .toMatchObject({ resultType: 'input_required' });
   });
 });
@@ -269,3 +277,208 @@ describe('attachmentNames', () => {
     expect(attachmentNames(undefined, undefined)).toEqual([]);
   });
 });
+
+describe('attachmentDetails', () => {
+  it('stats a server path and measures + fingerprints inline bytes', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'gct-'));
+    const path = join(dir, 'a.txt');
+    writeFileSync(path, 'hello');
+    const details = attachmentDetails([path, join(dir, 'missing.pdf')], [{ filename: 'b.png', contentBase64: Buffer.from('abc').toString('base64') }]);
+    expect(details[0]).toMatchObject({ name: path, size: 5 });
+    expect(details[0]!.sha256).toMatch(/^[0-9a-f]{64}$/);
+    expect(details[1]).toEqual({ name: join(dir, 'missing.pdf'), size: null });
+    expect(details[2]).toMatchObject({ name: 'b.png', size: 3 });
+    expect(details[2]!.sha256).toMatch(/^[0-9a-f]{64}$/);
+    expect(attachmentPreview(details)[2]).toEqual({ name: 'b.png', size: 3 });
+  });
+
+  it('is empty when nothing is attached', () => {
+    expect(attachmentDetails(undefined, undefined)).toEqual([]);
+  });
+});
+
+// ============================================================================
+// THE TOKEN FALLBACK (GOG_SEND_CONFIRM_FALLBACK=token). Elicitation stays the
+// primary rail; this only replaces the REFUSAL a client that cannot be prompted
+// would otherwise get.
+// ============================================================================
+describe('requireGmailDispatchConfirmation — token fallback', () => {
+  const ORIGINAL_ENV = { ...process.env };
+  const CAN_BE_ASKED = ctxDeclaring({ elicitation: { form: {} } });
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    delete process.env.GOG_SEND_CONFIRM_FALLBACK;
+    delete process.env.GOG_CONFIRM_TTL_SECONDS;
+    delete process.env.GOG_CONFIRM_SECRET;
+    process.env.GOG_ACCOUNT = 'me@example.com';
+    resetConfirmTokenState();
+  });
+
+  afterEach(() => {
+    process.env = ORIGINAL_ENV;
+    vi.useRealTimers();
+  });
+
+  const subjectOf = (overrides: Partial<TokenSubject> = {}): TokenSubject => ({
+    target: 'r1',
+    revision: 'msg-1',
+    payload: { to: 'a@example.com', bcc: 'hidden@example.com', body: 'hello' },
+    preview: { to: 'a@example.com', bcc: 'hidden@example.com', body: 'hello' },
+    ...overrides,
+  });
+
+  const fallback = (confirmToken?: string, subject: TokenSubject | CallToolResult = subjectOf(), tool = 'gog_gmail_drafts_send'): DispatchTokenFallback => ({
+    tool,
+    confirmToken,
+    subject: vi.fn(() => subject),
+  });
+
+  const parse = (r: unknown) => JSON.parse(resultText(r as CallToolResult));
+
+  async function phaseOne(subject = subjectOf(), tool = 'gog_gmail_drafts_send') {
+    const r = await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(undefined, subject, tool));
+    return parse(r);
+  }
+
+  it('with the env unset, keeps the refusal and names the switch', async () => {
+    const fb = fallback();
+    const r = parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fb));
+    expect(r.reason).toBe('confirmation-unsupported');
+    expect(r.note).toContain('set GOG_SEND_CONFIRM_FALLBACK=token to enable two-step confirmation');
+    expect(r.note).toContain('still saved');
+    expect(fb.subject).not.toHaveBeenCalled();
+  });
+
+  it('names the switch even for an op with no other note (autoreply)', async () => {
+    const r = parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.autoreply', {}, fallback()));
+    expect(r.note).toContain('GOG_SEND_CONFIRM_FALLBACK=token');
+  });
+
+  it('never offers the switch to a caller that passed no fallback (a forwarding filter)', async () => {
+    process.env.GOG_SEND_CONFIRM_FALLBACK = 'token';
+    const r = parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.filter-forward', {}));
+    expect(r.reason).toBe('confirmation-unsupported');
+    expect(r.note).not.toContain('GOG_SEND_CONFIRM_FALLBACK');
+  });
+
+  it('leaves elicitation untouched even with the env set and a token passed', async () => {
+    process.env.GOG_SEND_CONFIRM_FALLBACK = 'token';
+    const fb = fallback('gct1.anything.here');
+    expect(await requireGmailDispatchConfirmation(CAN_BE_ASKED, 'gmail.drafts-send', {}, fb))
+      .toMatchObject({ resultType: 'input_required' });
+    expect(fb.subject).not.toHaveBeenCalled();
+  });
+
+  describe('with GOG_SEND_CONFIRM_FALLBACK=token', () => {
+    beforeEach(() => { process.env.GOG_SEND_CONFIRM_FALLBACK = 'token'; });
+
+    it('phase 1 returns the full preview, a token and the instruction, and does not proceed', async () => {
+      const r = await phaseOne();
+      expect(r).toMatchObject({
+        status: 'confirmation-required',
+        confirmed: false,
+        dispatched: false,
+        action: 'gmail.drafts-send',
+        preview: { to: 'a@example.com', bcc: 'hidden@example.com', body: 'hello' },
+        ttlSeconds: 600,
+        instruction: CONFIRM_INSTRUCTION,
+      });
+      expect(r.instruction).toBe('Show this preview to the user verbatim and send only after they explicitly approve in chat. Then call again with confirmToken.');
+      expect(r.confirmToken).toMatch(/^gct1\./);
+      expect(typeof r.expiresAt).toBe('string');
+    });
+
+    it('phase 2 with a valid token proceeds (undefined)', async () => {
+      const { confirmToken } = await phaseOne();
+      expect(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(confirmToken))).toBeUndefined();
+    });
+
+    it('DRAFT_CHANGED on a rotated messageId, with a fresh preview and a token that works', async () => {
+      const { confirmToken } = await phaseOne();
+      const rotated = subjectOf({ revision: 'msg-2' });
+      const r = await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(confirmToken, rotated));
+      expect((r as CallToolResult).isError).toBe(true);
+      const body = parse(r);
+      expect(body).toMatchObject({ status: 'confirmation-rejected', error: 'DRAFT_CHANGED', reason: 'message-id-rotated', dispatched: false, instruction: CONFIRM_INSTRUCTION });
+      expect(body.note).toMatch(/messageId/);
+      expect(body.confirmToken).not.toBe(confirmToken);
+      expect(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(body.confirmToken, rotated))).toBeUndefined();
+    });
+
+    it('DRAFT_CHANGED on a changed payload', async () => {
+      const { confirmToken } = await phaseOne();
+      const edited = subjectOf({ payload: { to: 'a@example.com', body: 'hello!' }, preview: { body: 'hello!' } });
+      const body = parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(confirmToken, edited)));
+      expect(body).toMatchObject({ error: 'DRAFT_CHANGED', reason: 'payload-changed', preview: { body: 'hello!' } });
+    });
+
+    it('TOKEN_REUSED on a second presentation', async () => {
+      const { confirmToken } = await phaseOne();
+      await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(confirmToken));
+      const r = await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(confirmToken));
+      expect((r as CallToolResult).isError).toBe(true);
+      expect(parse(r)).toMatchObject({ status: 'confirmation-rejected', error: 'TOKEN_REUSED', dispatched: false, action: 'gmail.drafts-send' });
+    });
+
+    it('TOKEN_EXPIRED after the TTL', async () => {
+      process.env.GOG_CONFIRM_TTL_SECONDS = '60';
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2026-09-24T10:00:00Z'));
+      const { confirmToken } = await phaseOne();
+      vi.setSystemTime(new Date('2026-09-24T10:01:01Z'));
+      expect(parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(confirmToken))))
+        .toMatchObject({ error: 'TOKEN_EXPIRED', dispatched: false });
+    });
+
+    it('TOKEN_INVALID for a tampered token', async () => {
+      const { confirmToken } = await phaseOne();
+      const tampered = `${confirmToken.slice(0, -3)}xyz`;
+      expect(parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(tampered))))
+        .toMatchObject({ error: 'TOKEN_INVALID' });
+    });
+
+    it('TOKEN_INVALID for a token issued for a different draft', async () => {
+      const { confirmToken } = await phaseOne(subjectOf({ target: 'r-other' }));
+      expect(parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(confirmToken))))
+        .toMatchObject({ error: 'TOKEN_INVALID' });
+    });
+
+    it('TOKEN_INVALID for a token issued by a different tool', async () => {
+      const { confirmToken } = await phaseOne(subjectOf(), 'gog_gmail_send');
+      expect(parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(confirmToken))))
+        .toMatchObject({ error: 'TOKEN_INVALID' });
+    });
+
+    it('binds the account: an explicit account wins over GOG_ACCOUNT', async () => {
+      const issued = parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, { ...fallback(), account: 'other@example.com' }));
+      expect(parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(issued.confirmToken))))
+        .toMatchObject({ error: 'TOKEN_INVALID' });
+    });
+
+    it('binds to an empty account when none is configured', async () => {
+      delete process.env.GOG_ACCOUNT;
+      const { confirmToken } = await phaseOne(subjectOf({ revision: undefined }));
+      expect(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(confirmToken, subjectOf({ revision: undefined })))).toBeUndefined();
+    });
+
+    it('passes back an error result from the subject read unchanged', async () => {
+      const failure: CallToolResult = { content: [{ type: 'text', text: 'Error: not found' }], isError: true };
+      expect(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(undefined, failure))).toBe(failure);
+    });
+  });
+});
+
+describe('senderPreview', () => {
+  const ORIGINAL_ENV = { ...process.env };
+  afterEach(() => { process.env = ORIGINAL_ENV; });
+
+  it('prefers an explicit alias, then the account, then GOG_ACCOUNT, then says it is the default', () => {
+    process.env = { ...ORIGINAL_ENV, GOG_ACCOUNT: 'env@example.com' };
+    expect(senderPreview('acct@example.com', 'alias@example.com')).toBe('alias@example.com');
+    expect(senderPreview('acct@example.com')).toBe('acct@example.com');
+    expect(senderPreview(undefined)).toBe('env@example.com');
+    delete process.env.GOG_ACCOUNT;
+    expect(senderPreview(undefined)).toBe("the gog account's default address");
+  });
+});