gogcli-mcp 4.4.0 → 4.5.0

package/src/dispatch-confirmation.ts

@@ -1,17 +1,14 @@
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import type { CallToolResult, InputRequiredResult, ServerContext } from '@modelcontextprotocol/server';
-import { callerAcceptsFormElicitation, readEnvVar, requireConfirmation, textResult } from '@chrischall/mcp-utils';
-import { z } from 'zod';
 import {
-  confirmTokenTtlSeconds,
-  hashSendPayload,
-  issueConfirmToken,
-  sendConfirmFallbackEnabled,
-  verifyConfirmToken,
-  type ConfirmBinding,
-  type ConfirmTokenError,
-} from './send-confirm-token.js';
+  CONFIRM_TOKEN_INSTRUCTION,
+  confirmationFromEnv,
+  readEnvVar,
+  requireConfirmationWithFallback,
+  type ConfirmSubject,
+} from '@chrischall/mcp-utils';
+import { confirmSpentStore } from './send-confirm-token.js';
 
 // ============================================================================
 // THE DISPATCH RAIL, service-neutral: every tool that reaches another person
@@ -20,9 +17,11 @@ import {
 //
 // Elicitation is primary: the host shows the preview and the model never holds
 // the approval. On a client that declares no elicitation (claude.ai, measured),
-// the call is refused — unless the call site supplies a `DispatchTokenFallback`
-// and the server opted in with GOG_SEND_CONFIRM_FALLBACK=token, in which case
-// the two-phase preview + confirmToken flow (send-confirm-token.ts) runs instead.
+// the call site's `DispatchTokenFallback` runs the two-phase preview +
+// confirmToken flow instead (mcp-utils' confirmationFromEnv +
+// requireConfirmationWithFallback), as the fleet's MCP_CONFIRM_MODE says:
+// ask-user (default), auto, or refuse. A call site with no fallback (the
+// forwarding filter) is always refused on such a client.
 // ============================================================================
 
 // Bound on the body text shown in a confirmation prompt. Enough to read what is
@@ -100,39 +99,23 @@ export const CONFIRM_SEND_INSTRUCTION =
   + 'Then call again with confirmToken.';
 
 /** The same instruction for a dispatch that is not mail (a share, an invitation, a post). */
-export const CONFIRM_ACTION_INSTRUCTION =
-  'Show this preview to the user verbatim and proceed only after they explicitly approve in chat. '
-  + 'Then call again with confirmToken.';
-
-const FALLBACK_HINT = 'Or set GOG_SEND_CONFIRM_FALLBACK=token to enable two-step confirmation.';
+export const CONFIRM_ACTION_INSTRUCTION = CONFIRM_TOKEN_INSTRUCTION;
 
 /** Appended to each gated tool's description. */
 export const CONFIRM_FALLBACK_DESCRIPTION =
-  ' If the client cannot show that prompt (no MCP elicitation, e.g. claude.ai) and the server sets '
-  + 'GOG_SEND_CONFIRM_FALLBACK=token, a two-step flow applies instead: call WITHOUT confirmToken and nothing is '
-  + 'sent or changed — the result has status "confirmation-required", the full preview and a confirmToken. Show that preview '
-  + 'to the user verbatim; only after they explicitly approve it in chat, call again with the SAME arguments plus '
-  + 'confirmToken. The tool re-reads what it would act on and refuses (DRAFT_CHANGED, with a fresh preview and token) '
-  + 'if it changed; TOKEN_EXPIRED / TOKEN_REUSED / TOKEN_INVALID also do nothing.';
+  ' If the client cannot show that prompt (no MCP elicitation, e.g. claude.ai), a two-step flow applies instead: call '
+  + 'WITHOUT confirmToken and nothing is sent or changed — the result has status "confirmation-required", the full '
+  + 'preview and a confirmToken. Follow its instruction (by default: show the preview to the user verbatim and only '
+  + 'after they explicitly approve it in chat, call again with the SAME arguments plus confirmToken). The tool re-reads '
+  + 'what it would act on and refuses (DRAFT_CHANGED, with a fresh preview and token) if it changed; TOKEN_EXPIRED / '
+  + 'TOKEN_REUSED / TOKEN_INVALID also do nothing. A server set to MCP_CONFIRM_MODE=refuse refuses instead.';
 
-export const confirmTokenParam = z.string().optional().describe(
-  'ONLY for the two-step fallback (client without MCP elicitation, server with GOG_SEND_CONFIRM_FALLBACK=token). '
-  + 'The confirmToken from this same tool\'s phase-1 "confirmation-required" response, passed back ONLY after the user '
-  + 'has seen that preview and explicitly approved it in chat — never on the first call, never invented, never '
-  + 'reused. Call again with the same arguments. Ignored when the client supports elicitation.',
-);
+// The schema input every gated tool adds: mcp-utils' own, so its wording and
+// the helper that reads it cannot drift apart.
+export { confirmTokenParam } from '@chrischall/mcp-utils';
 
 /** What the fallback binds a token to — recomputed from a fresh read on every call. */
-export interface TokenSubject {
-  /** The draftId / messageId / fileId / eventId / query the dispatch acts on. */
-  target: string;
-  /** A version that rotates on edit: a draft's messageId, an event's etag. */
-  revision?: string;
-  /** Canonical send payload; its SHA-256 is bound into the token. */
-  payload: unknown;
-  /** The complete preview shown to the user. */
-  preview: Record<string, unknown>;
-}
+export type TokenSubject = ConfirmSubject;
 
 /**
  * Opt-in second rail for a client that cannot be prompted. `subject` is only
@@ -149,66 +132,6 @@ export interface DispatchTokenFallback {
   subject: () => TokenSubject | CallToolResult | Promise<TokenSubject | CallToolResult>;
 }
 
-const TOKEN_ERROR_NOTE: Record<Exclude<ConfirmTokenError, 'DRAFT_CHANGED'>, string> = {
-  TOKEN_EXPIRED: 'Nothing was sent or changed: the confirmToken expired. Call again WITHOUT confirmToken for a fresh preview, '
-    + 'and ask the user to approve it again.',
-  TOKEN_REUSED: 'Nothing was sent or changed by this call: this confirmToken was already used, and one approval acts once. '
-    + 'If doing it again is really intended, call again WITHOUT confirmToken and get a new approval.',
-  TOKEN_INVALID: 'Nothing was sent or changed: this confirmToken was not issued by this server for this tool, account and '
-    + 'target (or the server has restarted since). Call again WITHOUT confirmToken for a fresh preview and approval.',
-};
-
-const DRAFT_CHANGED_NOTE = {
-  'message-id-rotated': 'Nothing was sent or changed: the target was edited since the user approved it (a draft\'s '
-    + 'messageId or an event\'s version rotated), so what would happen is not what they saw.',
-  'payload-changed': 'Nothing was sent or changed: what would happen no longer matches what the user approved.',
-} as const;
-
-function isToolResult(value: TokenSubject | CallToolResult): value is CallToolResult {
-  return Array.isArray((value as CallToolResult).content);
-}
-
-function rejection(data: Record<string, unknown>): CallToolResult {
-  return { ...textResult({ status: 'confirmation-rejected', confirmed: false, dispatched: false, ...data }), isError: true };
-}
-
-async function tokenConfirmation(op: string, fallback: DispatchTokenFallback): Promise<CallToolResult | undefined> {
-  const subject = await fallback.subject();
-  if (isToolResult(subject)) return subject;
-  const binding: ConfirmBinding = {
-    tool: fallback.tool,
-    account: fallback.account ?? readEnvVar('GOG_ACCOUNT') ?? '',
-    target: subject.target,
-    ...(subject.revision === undefined ? {} : { revision: subject.revision }),
-    payloadHash: hashSendPayload(subject.payload),
-  };
-  const phaseOne = () => {
-    const { token, expiresAt } = issueConfirmToken(binding);
-    return {
-      action: op,
-      preview: subject.preview,
-      confirmToken: token,
-      expiresAt,
-      ttlSeconds: confirmTokenTtlSeconds(),
-      instruction: fallback.instruction ?? CONFIRM_ACTION_INSTRUCTION,
-    };
-  };
-  if (!fallback.confirmToken) {
-    return textResult({ status: 'confirmation-required', confirmed: false, dispatched: false, ...phaseOne() });
-  }
-  const verdict = verifyConfirmToken(fallback.confirmToken, binding);
-  if (verdict.ok) return undefined;
-  if (verdict.error === 'DRAFT_CHANGED') {
-    return rejection({
-      error: 'DRAFT_CHANGED',
-      reason: verdict.reason,
-      note: `${DRAFT_CHANGED_NOTE[verdict.reason!]} The current preview and a fresh confirmToken are below.`,
-      ...phaseOne(),
-    });
-  }
-  return rejection({ error: verdict.error, action: op, note: TOKEN_ERROR_NOTE[verdict.error] });
-}
-
 /**
  * The refusal an escape hatch (`gog_<service>_run`, `gog_api_call`) gives for an
  * action a dedicated tool gates. Without it, the run tool is a way around the
@@ -242,29 +165,33 @@ export interface DispatchConfirmationOptions {
  * Ask the user before a dispatch. `undefined` means proceed; anything else is
  * the result to return unchanged.
  *
- * Elicitation stays the primary path and is untouched. Only when the caller
- * declares it cannot be prompted AND a `fallback` is supplied AND
- * GOG_SEND_CONFIRM_FALLBACK=token does the two-phase token flow run instead of
- * the refusal; with the env unset, the refusal names that switch.
+ * Elicitation stays the primary path and is untouched. When the caller
+ * declares it cannot be prompted AND a `fallback` is supplied, MCP_CONFIRM_MODE
+ * decides: ask-user (default) or auto run the two-phase token flow; refuse
+ * refuses and names the switch. Without a fallback it is always refused.
  */
 export async function requireDispatchConfirmation(
   ctx: ServerContext,
   options: DispatchConfirmationOptions,
 ): Promise<InputRequiredResult | CallToolResult | undefined> {
   const { action, fallback } = options;
-  if (fallback && callerAcceptsFormElicitation(ctx) === false && sendConfirmFallbackEnabled()) {
-    return tokenConfirmation(action, fallback);
-  }
-  const note = fallback
-    ? [options.unsupportedNote, FALLBACK_HINT].filter(Boolean).join(' ')
-    : options.unsupportedNote;
-  return requireConfirmation(ctx, {
+  const confirmation = {
     action,
     message: options.message,
     details: options.details,
     confirmationLabel: options.confirmationLabel,
-    ...(note ? { unsupportedNote: note } : {}),
-  });
+    ...(options.unsupportedNote ? { unsupportedNote: options.unsupportedNote } : {}),
+  };
+  if (!fallback) return requireConfirmationWithFallback(ctx, confirmation);
+  return requireConfirmationWithFallback(ctx, confirmationFromEnv({
+    ...confirmation,
+    tool: fallback.tool,
+    account: fallback.account ?? readEnvVar('GOG_ACCOUNT') ?? '',
+    confirmToken: fallback.confirmToken,
+    subject: fallback.subject,
+    instruction: fallback.instruction ?? CONFIRM_ACTION_INSTRUCTION,
+    spent: confirmSpentStore(),
+  }));
 }
 
 // The single place a CallToolResult's text is pulled back out, for the tools

package/src/gmail-dispatch-guard.ts

@@ -32,11 +32,11 @@ export type { AttachmentDetail, DispatchTokenFallback, TokenSubject } from './di
 // user's accepted confirmation dispatches. The confirmation is never a tool
 // argument, so a model cannot bypass the user by setting a boolean itself.
 //
-// The one exception is OPT-IN: with GOG_SEND_CONFIRM_FALLBACK=token, a client
-// that cannot be prompted gets a two-phase preview + confirmToken instead of a
-// refusal (`DispatchTokenFallback`, send-confirm-token.ts). There the approval
-// IS a tool argument; see that file for exactly what the token does and does
-// not guarantee.
+// The one exception: a client that cannot be prompted gets a two-phase preview
+// + confirmToken instead of a refusal (`DispatchTokenFallback`; mcp-utils'
+// confirmationFromEnv), unless the server sets MCP_CONFIRM_MODE=refuse. There
+// the approval IS a tool argument; see mcp-utils' confirm-token module for
+// exactly what the token does and does not guarantee.
 //
 // A CLIENT THAT CANNOT SHOW THAT PROMPT gets a sentence rather than a prompt
 // it will refuse to deliver (`unsupportedNote`, mcp-utils `requireConfirmation`).
@@ -123,10 +123,10 @@ const UNSUPPORTED_NOTE: Partial<Record<GmailDispatchOp, string>> = {
 /**
  * Apply the shared stateless confirmation flow with Gmail-specific copy.
  *
- * Elicitation stays the primary path and is untouched. Only when the caller
- * declares it cannot be prompted AND a `fallback` is supplied AND
- * GOG_SEND_CONFIRM_FALLBACK=token does the two-phase token flow run instead of
- * the refusal; with the env unset, the refusal names that switch.
+ * Elicitation stays the primary path and is untouched. When the caller
+ * declares it cannot be prompted AND a `fallback` is supplied, MCP_CONFIRM_MODE
+ * decides: ask-user (default) or auto run the two-phase token flow; refuse
+ * refuses and names the switch.
  */
 export async function requireGmailDispatchConfirmation(
   ctx: ServerContext,

package/src/send-confirm-token.ts

@@ -1,167 +1,29 @@
-import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
-import { readEnvVar } from '@chrischall/mcp-utils';
+import { createSpentTokenStore, type SpentTokenStore } from '@chrischall/mcp-utils';
 
 // ============================================================================
-// THE TOKEN FALLBACK for the Gmail dispatch rail (gmail-dispatch-guard.ts).
+// THE TOKEN FALLBACK's gogcli-mcp half, which is now only its spent-token store.
+// Everything else is the fleet's shared layer in @chrischall/mcp-utils
+// (`confirmationFromEnv` + `requireConfirmationWithFallback`), configured by the
+// same three variables as every other fleet server:
 //
-// A client with no MCP elicitation (claude.ai, measured) cannot be shown the
-// confirmation prompt, so every send is refused there. With
-// GOG_SEND_CONFIRM_FALLBACK=token the rail instead runs two phases: phase 1
-// returns the full preview plus a token and sends nothing; phase 2 presents the
-// token, the tool RE-READS what it would send, and dispatches only if that still
-// hashes to what the token was issued for.
+//   MCP_CONFIRM_MODE         ask-user (default) | auto | refuse
+//   MCP_CONFIRM_TTL_SECONDS  token lifetime, default 600
+//   MCP_CONFIRM_SECRET       HMAC key; default random per process
 //
-// WHAT THIS DOES AND DOES NOT PROVE. Unlike elicitation, the approval here is a
-// tool argument, so the gate is the model honouring "show this to the user and
-// wait". The token cannot make the model ask; what it guarantees is that what
-// is sent matches what was previewed — a draft edited in a mail client (its
-// messageId rotates), a changed recipient or body, or a swapped attachment
-// between the two calls all refuse. Caller-supplied files are bound by content
-// hash; a stored draft's attachments by name and size, since Gmail's
-// attachment ids are unstable and any edit rotates the messageId anyway. One
-// approval acts once, for one tool, account and target, within the TTL — per
-// PROCESS: spent tokens live in memory, so with a shared GOG_CONFIRM_SECRET a
-// restart or a second instance would accept a spent token again until it
-// expires. That is why the mode is opt-in.
+// WHAT THIS DOES AND DOES NOT PROVE: see mcp-utils' confirm-token module. The
+// approval is a tool argument, so under ask-user the gate is the model honouring
+// "show this to the user and wait"; the token guarantees what happens matches
+// what was previewed, once, for one tool, account and target.
 // ============================================================================
 
-export type ConfirmTokenError = 'DRAFT_CHANGED' | 'TOKEN_EXPIRED' | 'TOKEN_REUSED' | 'TOKEN_INVALID';
+const spent = createSpentTokenStore();
 
-/** What a token is bound to. Every field must match on phase 2. */
-export interface ConfirmBinding {
-  tool: string;
-  account: string;
-  /** The draftId / messageId / query the dispatch acts on. */
-  target: string;
-  /** A version of the target that rotates on edit — a draft's messageId. */
-  revision?: string;
-  /** {@link hashSendPayload} of the canonical send payload. */
-  payloadHash: string;
+/** This server's spent-token store (one per process). */
+export function confirmSpentStore(): SpentTokenStore {
+  return spent;
 }
 
-export type ConfirmTokenVerdict =
-  | { ok: true }
-  | { ok: false; error: ConfirmTokenError; reason?: 'payload-changed' | 'message-id-rotated' };
-
-export const CONFIRM_TOKEN_TTL_DEFAULT_SECONDS = 600;
-
-const PREFIX = 'gct1';
-
-type Claims = { t: string; a: string; g: string; r?: string; h: string; iat: number; exp: number; n: string };
-
-let secret: Buffer | undefined;
-// nonce → expiry (ms). Entries are dropped once they would have expired
-// anyway, so the set is bounded by the tokens spent within one TTL. In memory
-// only: see the header on GOG_CONFIRM_SECRET and restarts.
-const spent = new Map<string, number>();
-
-/** GOG_SEND_CONFIRM_FALLBACK=token turns the fallback on. Anything else is off. */
-export function sendConfirmFallbackEnabled(): boolean {
-  return readEnvVar('GOG_SEND_CONFIRM_FALLBACK')?.trim().toLowerCase() === 'token';
-}
-
-export function confirmTokenTtlSeconds(): number {
-  const raw = readEnvVar('GOG_CONFIRM_TTL_SECONDS')?.trim();
-  if (raw && /^\d+$/.test(raw)) {
-    const n = Number(raw);
-    if (n > 0) return n;
-  }
-  return CONFIRM_TOKEN_TTL_DEFAULT_SECONDS;
-}
-
-// GOG_CONFIRM_SECRET ends in _SECRET, so runner.ts strips it from every gog
-// child — it never leaves this process.
-function hmacKey(): Buffer {
-  if (!secret) {
-    const configured = readEnvVar('GOG_CONFIRM_SECRET');
-    secret = configured ? Buffer.from(configured, 'utf8') : randomBytes(32);
-  }
-  return secret;
-}
-
-/** Test seam: forget the secret (a "restart") and every spent token. */
+/** Test seam: forget every spent token. */
 export function resetConfirmTokenState(): void {
-  secret = undefined;
   spent.clear();
 }
-
-// Sorted keys, undefined dropped: the same payload re-read on phase 2 must
-// hash identically however its object was assembled.
-function canonicalize(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(canonicalize);
-  if (value && typeof value === 'object') {
-    const out: Record<string, unknown> = {};
-    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
-      const v = (value as Record<string, unknown>)[key];
-      if (v !== undefined) out[key] = canonicalize(v);
-    }
-    return out;
-  }
-  return value;
-}
-
-/** SHA-256 (hex) of the canonical JSON of a send payload. */
-export function hashSendPayload(payload: unknown): string {
-  return createHash('sha256').update(JSON.stringify(canonicalize(payload))).digest('hex');
-}
-
-function sign(body: string): string {
-  return createHmac('sha256', hmacKey()).update(`${PREFIX}.${body}`).digest('base64url');
-}
-
-export function issueConfirmToken(binding: ConfirmBinding, now = Date.now()): { token: string; expiresAt: string } {
-  const exp = now + confirmTokenTtlSeconds() * 1000;
-  const claims: Claims = {
-    t: binding.tool,
-    a: binding.account,
-    g: binding.target,
-    ...(binding.revision === undefined ? {} : { r: binding.revision }),
-    h: binding.payloadHash,
-    iat: now,
-    exp,
-    n: randomBytes(16).toString('base64url'),
-  };
-  const body = Buffer.from(JSON.stringify(claims), 'utf8').toString('base64url');
-  return { token: `${PREFIX}.${body}.${sign(body)}`, expiresAt: new Date(exp).toISOString() };
-}
-
-function signatureMatches(body: string, sig: string): boolean {
-  const expected = Buffer.from(sign(body), 'utf8');
-  const actual = Buffer.from(sig, 'utf8');
-  return expected.length === actual.length && timingSafeEqual(expected, actual);
-}
-
-function parseClaims(body: string): Claims | undefined {
-  try {
-    return JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as Claims;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Check a phase-2 token against the binding recomputed from a fresh re-read.
- * Only an `ok` verdict consumes the token; a DRAFT_CHANGED leaves it unspent,
- * because the approval it carries is still true of the content it names.
- */
-export function verifyConfirmToken(token: string, binding: ConfirmBinding, now = Date.now()): ConfirmTokenVerdict {
-  for (const [nonce, exp] of spent) if (exp < now) spent.delete(nonce);
-
-  const parts = token.split('.');
-  if (parts.length !== 3 || parts[0] !== PREFIX || !parts[1] || !parts[2]) return { ok: false, error: 'TOKEN_INVALID' };
-  const [, body, sig] = parts as [string, string, string];
-  if (!signatureMatches(body, sig)) return { ok: false, error: 'TOKEN_INVALID' };
-  const claims = parseClaims(body);
-  if (!claims) return { ok: false, error: 'TOKEN_INVALID' };
-
-  if (claims.t !== binding.tool || claims.a !== binding.account || claims.g !== binding.target) {
-    return { ok: false, error: 'TOKEN_INVALID' };
-  }
-  if (spent.has(claims.n)) return { ok: false, error: 'TOKEN_REUSED' };
-  if (now > claims.exp) return { ok: false, error: 'TOKEN_EXPIRED' };
-  if (claims.r !== binding.revision) return { ok: false, error: 'DRAFT_CHANGED', reason: 'message-id-rotated' };
-  if (claims.h !== binding.payloadHash) return { ok: false, error: 'DRAFT_CHANGED', reason: 'payload-changed' };
-
-  spent.set(claims.n, claims.exp);
-  return { ok: true };
-}

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

@@ -298,7 +298,7 @@ describe('attachmentDetails', () => {
 });
 
 // ============================================================================
-// THE TOKEN FALLBACK (GOG_SEND_CONFIRM_FALLBACK=token). Elicitation stays the
+// THE TOKEN FALLBACK (MCP_CONFIRM_MODE, default ask-user). Elicitation stays the
 // primary rail; this only replaces the REFUSAL a client that cannot be prompted
 // would otherwise get.
 // ============================================================================
@@ -308,9 +308,9 @@ describe('requireGmailDispatchConfirmation — token fallback', () => {
 
   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;
+    delete process.env.MCP_CONFIRM_MODE;
+    delete process.env.MCP_CONFIRM_TTL_SECONDS;
+    delete process.env.MCP_CONFIRM_SECRET;
     process.env.GOG_ACCOUNT = 'me@example.com';
     resetConfirmTokenState();
   });
@@ -341,37 +341,56 @@ describe('requireGmailDispatchConfirmation — token fallback', () => {
     return parse(r);
   }
 
-  it('with the env unset, keeps the refusal and names the switch', async () => {
+  it('with MCP_CONFIRM_MODE=refuse, keeps the refusal and names the switch', async () => {
+
+    process.env.MCP_CONFIRM_MODE = 'refuse';
     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('Set MCP_CONFIRM_MODE=ask-user');
     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 () => {
+
+    process.env.MCP_CONFIRM_MODE = 'refuse';
     const r = parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.autoreply', {}, fallback()));
-    expect(r.note).toContain('GOG_SEND_CONFIRM_FALLBACK=token');
+    expect(r.note).toContain('MCP_CONFIRM_MODE=ask-user');
   });
 
   it('never offers the switch to a caller that passed no fallback (a forwarding filter)', async () => {
-    process.env.GOG_SEND_CONFIRM_FALLBACK = 'token';
+    process.env.MCP_CONFIRM_MODE = 'ask-user';
     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');
+    expect(r.note).not.toContain('MCP_CONFIRM_MODE');
   });
 
   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');
+    process.env.MCP_CONFIRM_MODE = 'ask-user';
+    const fb = fallback('not-a-real-token');
     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'; });
+  // The fleet default: with MCP_CONFIRM_MODE unset, a client that cannot be
+  // prompted gets the two-step flow rather than a refusal.
+  it('with MCP_CONFIRM_MODE unset, runs the two-step flow (ask-user is the default)', async () => {
+    const r = parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback()));
+    expect(r).toMatchObject({ status: 'confirmation-required', instruction: CONFIRM_INSTRUCTION });
+  });
+
+  it('with MCP_CONFIRM_MODE=auto, tells the model it may proceed after reviewing the preview', async () => {
+    process.env.MCP_CONFIRM_MODE = 'auto';
+    const r = parse(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback()));
+    expect(r.status).toBe('confirmation-required');
+    expect(r.instruction).toMatch(/MCP_CONFIRM_MODE=auto/);
+    expect(r.instruction).not.toBe(CONFIRM_INSTRUCTION);
+  });
+
+  describe('with MCP_CONFIRM_MODE=ask-user', () => {
+    beforeEach(() => { process.env.MCP_CONFIRM_MODE = 'ask-user'; });
 
     it('phase 1 returns the full preview, a token and the instruction, and does not proceed', async () => {
       const r = await phaseOne();
@@ -385,7 +404,7 @@ describe('requireGmailDispatchConfirmation — token fallback', () => {
         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(r.confirmToken).toMatch(/^mcpu\.token\.v1\./);
       expect(typeof r.expiresAt).toBe('string');
     });
 
@@ -400,8 +419,8 @@ describe('requireGmailDispatchConfirmation — token fallback', () => {
       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).toMatchObject({ status: 'confirmation-rejected', error: 'DRAFT_CHANGED', reason: 'revision-changed', dispatched: false, instruction: CONFIRM_INSTRUCTION });
+      expect(body.note).toMatch(/edited since/);
       expect(body.confirmToken).not.toBe(confirmToken);
       expect(await requireGmailDispatchConfirmation(CANNOT_BE_ASKED, 'gmail.drafts-send', {}, fallback(body.confirmToken, rotated))).toBeUndefined();
     });
@@ -422,7 +441,7 @@ describe('requireGmailDispatchConfirmation — token fallback', () => {
     });
 
     it('TOKEN_EXPIRED after the TTL', async () => {
-      process.env.GOG_CONFIRM_TTL_SECONDS = '60';
+      process.env.MCP_CONFIRM_TTL_SECONDS = '60';
       vi.useFakeTimers();
       vi.setSystemTime(new Date('2026-09-24T10:00:00Z'));
       const { confirmToken } = await phaseOne();