gogcli-mcp 4.3.0 → 4.4.0

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "mcpName": "io.github.chrischall/gogcli-mcp",
   "description": "MCP server wrapping gogcli for Google service access",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp"
   },
-  "version": "4.3.0",
+  "version": "4.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp",
-      "version": "4.3.0",
+      "version": "4.4.0",
       "transport": {
         "type": "stdio"
       },

package/src/dispatch-confirmation.ts

@@ -0,0 +1,277 @@
+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';
+
+// ============================================================================
+// THE DISPATCH RAIL, service-neutral: every tool that reaches another person
+// (Gmail sends, Chat posts, guest-visible Calendar changes, Drive shares,
+// Classroom announcements and invitations) asks the user first.
+//
+// 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.
+// ============================================================================
+
+// Bound on the body text shown in a confirmation prompt. Enough to read what is
+// actually being sent (the point of SEC-5), small enough to keep the prompt a
+// prompt rather than a copy of the message.
+export const BODY_PREVIEW_MAX = 2048;
+
+/** The first BODY_PREVIEW_MAX characters of a body, marked when cut. */
+export function bodyPreview(text: string | undefined): string | undefined {
+  if (!text) return undefined;
+  if (text.length <= BODY_PREVIEW_MAX) return text;
+  return `${text.slice(0, BODY_PREVIEW_MAX)}… [${text.length - BODY_PREVIEW_MAX} more characters not shown]`;
+}
+
+/**
+ * Every attachment a dispatch will carry: a server path in full (so the user
+ * sees WHICH file on the gog host is leaving), an inline one by its filename.
+ */
+export function attachmentNames(
+  paths: readonly string[] | undefined,
+  inline: ReadonlyArray<{ filename: string }> | undefined,
+): string[] {
+  return [...(paths ?? []), ...(inline ?? []).map((a) => a.filename)];
+}
+
+/** One attachment as the fallback preview shows it and its hash binds it. */
+export type AttachmentDetail = { name: string; size: number | null; sha256?: string };
+
+/**
+ * Name, byte size and content SHA-256 of every file a dispatch carries, for the
+ * token fallback's preview and payload hash. A server path is read (it is
+ * already confined to GOG_FILE_ROOTS) so a same-size swap between the phases is
+ * still a changed payload; an unreadable one reports `size: null` and gog will
+ * fail on it anyway.
+ */
+export function attachmentDetails(
+  paths: readonly string[] | undefined,
+  inline: ReadonlyArray<{ filename: string; contentBase64: string }> | undefined,
+): AttachmentDetail[] {
+  const out: AttachmentDetail[] = [];
+  for (const path of paths ?? []) {
+    let bytes: Buffer | undefined;
+    try {
+      bytes = readFileSync(path);
+    } catch {
+      bytes = undefined;
+    }
+    out.push(bytes
+      ? { name: path, size: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') }
+      : { name: path, size: null });
+  }
+  for (const a of inline ?? []) {
+    out.push({
+      name: a.filename,
+      size: Buffer.from(a.contentBase64, 'base64').length,
+      sha256: createHash('sha256').update(a.contentBase64).digest('hex'),
+    });
+  }
+  return out;
+}
+
+/** Who a dispatch goes out as, for the fallback preview: an explicit alias, else the account. */
+export function senderPreview(account: string | undefined, from?: string): string {
+  return from ?? account ?? readEnvVar('GOG_ACCOUNT') ?? "the gog account's default address";
+}
+
+/** Drop the fingerprint for display: the user needs a name and a size. */
+export function attachmentPreview(details: readonly AttachmentDetail[]): Array<{ name: string; size: number | null }> {
+  return details.map(({ name, size }) => ({ name, size }));
+}
+
+/** The instruction a mail dispatch's phase 1 carries — verbatim from the spec that introduced the fallback. */
+export const CONFIRM_SEND_INSTRUCTION =
+  'Show this preview to the user verbatim and send only after they explicitly approve in chat. '
+  + '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.';
+
+/** 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.';
+
+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.',
+);
+
+/** 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>;
+}
+
+/**
+ * Opt-in second rail for a client that cannot be prompted. `subject` is only
+ * called when the fallback actually runs, so a tool may do an extra read there
+ * without changing the elicitation path at all. It may return an error result
+ * (a failed read), which is passed back unchanged.
+ */
+export interface DispatchTokenFallback {
+  tool: string;
+  account?: string;
+  confirmToken?: string;
+  /** Phase 1's instruction to the model. Defaults to {@link CONFIRM_ACTION_INSTRUCTION}. */
+  instruction?: string;
+  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
+ * rail: the model forwards the same subcommand and nobody is asked (#400).
+ */
+export function gatedElsewhere(what: string, via: string, does: string, tool: string): string {
+  return `${what} ${does} and is not available through ${via}. Use ${tool}, which asks the user to confirm.`;
+}
+
+/** True when any forwarded token is one of `words` (kong lets flags precede the command word). */
+export function hasCommandWord(args: readonly string[], words: ReadonlySet<string>): string | undefined {
+  return args.find((a) => words.has(a.toLowerCase()));
+}
+
+export interface DispatchConfirmationOptions {
+  /** Stable id of the dispatch, echoed in every result (`gmail.send`, `drive.share`, …). */
+  action: string;
+  /** Heading of the elicitation prompt. */
+  message: string;
+  /** Label beside the prompt's confirmation checkbox. */
+  confirmationLabel: string;
+  /** What the elicitation prompt shows. */
+  details: Record<string, unknown>;
+  /** The way through on a client that cannot be prompted, when there is one. */
+  unsupportedNote?: string;
+  /** Opt-in second rail; omit it and a client that cannot be prompted is always refused. */
+  fallback?: DispatchTokenFallback;
+}
+
+/**
+ * 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.
+ */
+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, {
+    action,
+    message: options.message,
+    details: options.details,
+    confirmationLabel: options.confirmationLabel,
+    ...(note ? { unsupportedNote: note } : {}),
+  });
+}
+
+// The single place a CallToolResult's text is pulled back out, for the tools
+// here that need to read gog's own JSON before deciding what to preview or
+// log. Mirrors the shape every runOrDiagnose result actually returns
+// (content[0].text); never throws on an unexpected shape.
+export function resultText(result: CallToolResult): string {
+  const first = result.content[0];
+  return first && first.type === 'text' && typeof first.text === 'string' ? first.text : '{}';
+}

package/src/gmail-dispatch-guard.ts

@@ -1,5 +1,22 @@
 import type { CallToolResult, InputRequiredResult, ServerContext } from '@modelcontextprotocol/server';
-import { readEnvVar, requireConfirmation } from '@chrischall/mcp-utils';
+import { readEnvVar } from '@chrischall/mcp-utils';
+import { CONFIRM_SEND_INSTRUCTION, requireDispatchConfirmation, type DispatchTokenFallback } from './dispatch-confirmation.js';
+
+// The generic pieces moved to dispatch-confirmation.ts when Chat, Calendar,
+// Drive and Classroom joined the rail; re-exported so Gmail callers keep one import.
+export {
+  attachmentDetails,
+  attachmentNames,
+  BODY_PREVIEW_MAX,
+  bodyPreview,
+  attachmentPreview,
+  CONFIRM_FALLBACK_DESCRIPTION,
+  CONFIRM_SEND_INSTRUCTION as CONFIRM_INSTRUCTION,
+  confirmTokenParam,
+  resultText,
+  senderPreview,
+} from './dispatch-confirmation.js';
+export type { AttachmentDetail, DispatchTokenFallback, TokenSubject } from './dispatch-confirmation.js';
 
 // ============================================================================
 // THE SAFETY RAIL. gog_gmail_reply / reply_all / send / forward / autoreply /
@@ -15,6 +32,12 @@ import { readEnvVar, requireConfirmation } from '@chrischall/mcp-utils';
 // 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.
+//
 // A CLIENT THAT CANNOT SHOW THAT PROMPT gets a sentence rather than a prompt
 // it will refuse to deliver (`unsupportedNote`, mcp-utils `requireConfirmation`).
 // Measured on the mcp-host fleet 2026-09-20: claude.ai declares no MCP
@@ -97,41 +120,26 @@ const UNSUPPORTED_NOTE: Partial<Record<GmailDispatchOp, string>> = {
   'gmail.drafts-send': 'The draft is still saved: ask the user to review it and send it from Gmail.',
 };
 
-// Bound on the body text shown in a confirmation prompt. Enough to read what is
-// actually being sent (the point of SEC-5), small enough to keep the prompt a
-// prompt rather than a copy of the message.
-export const BODY_PREVIEW_MAX = 2048;
-
-/** The first BODY_PREVIEW_MAX characters of a body, marked when cut. */
-export function bodyPreview(text: string | undefined): string | undefined {
-  if (!text) return undefined;
-  if (text.length <= BODY_PREVIEW_MAX) return text;
-  return `${text.slice(0, BODY_PREVIEW_MAX)}… [${text.length - BODY_PREVIEW_MAX} more characters not shown]`;
-}
-
 /**
- * Every attachment a dispatch will carry: a server path in full (so the user
- * sees WHICH file on the gog host is leaving), an inline one by its filename.
+ * 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.
  */
-export function attachmentNames(
-  paths: readonly string[] | undefined,
-  inline: ReadonlyArray<{ filename: string }> | undefined,
-): string[] {
-  return [...(paths ?? []), ...(inline ?? []).map((a) => a.filename)];
-}
-
-/** Apply the shared stateless confirmation flow with Gmail-specific copy. */
-export function requireGmailDispatchConfirmation(
+export async function requireGmailDispatchConfirmation(
   ctx: ServerContext,
   op: GmailDispatchOp,
   details: Record<string, unknown>,
-): InputRequiredResult | CallToolResult | undefined {
+  fallback?: DispatchTokenFallback,
+): Promise<InputRequiredResult | CallToolResult | undefined> {
   const twin = STAGING_TWIN[op];
   const note = twin
     ? `Stage it with ${twin} instead; the user can review the draft and send it from Gmail `
       + '(gog_gmail_drafts_send also asks for confirmation).'
     : UNSUPPORTED_NOTE[op];
-  return requireConfirmation(ctx, {
+  return requireDispatchConfirmation(ctx, {
     action: op,
     message: op === 'gmail.filter-forward'
       ? 'Review and confirm this mail-forwarding filter:'
@@ -140,7 +148,8 @@ export function requireGmailDispatchConfirmation(
     confirmationLabel: op === 'gmail.filter-forward'
       ? 'Confirm that matching mail should be forwarded automatically from now on.'
       : 'Confirm that this email should be sent now.',
-    ...(note ? { unsupportedNote: note } : {}),
+    unsupportedNote: note,
+    ...(fallback ? { fallback: { instruction: CONFIRM_SEND_INSTRUCTION, ...fallback } } : {}),
   });
 }
 
@@ -210,12 +219,3 @@ export function logGmailDispatch(tool: string, recipients: string[], account?: s
   };
   process.stderr.write(`${JSON.stringify(event)}\n`);
 }
-
-// The single place a CallToolResult's text is pulled back out, for the tools
-// here that need to read gog's own JSON before deciding what to preview or
-// log. Mirrors the shape every runOrDiagnose result actually returns
-// (content[0].text); never throws on an unexpected shape.
-export function resultText(result: CallToolResult): string {
-  const first = result.content[0];
-  return first && first.type === 'text' && typeof first.text === 'string' ? first.text : '{}';
-}

package/src/lib.ts

@@ -26,13 +26,22 @@ export type { ReplyFlags } from './tools/gmail.js';
 // gmail sub-package's send-side forward/autoreply tools reuse these directly
 // rather than re-declaring the gate; the draft-side twins never import them.
 export {
+  attachmentDetails,
   attachmentNames,
+  attachmentPreview,
   bodyPreview,
+  CONFIRM_FALLBACK_DESCRIPTION,
+  confirmTokenParam,
   extractEmails,
   logGmailDispatch,
   requireGmailDispatchConfirmation,
   resultText,
+  senderPreview,
 } from './gmail-dispatch-guard.js';
+// The service-neutral rail for every other tool that reaches another person.
+export { requireDispatchConfirmation } from './dispatch-confirmation.js';
+export { readCourse } from './tools/classroom.js';
+export type { AttachmentDetail, DispatchTokenFallback, TokenSubject } from './gmail-dispatch-guard.js';
 export { run, runBinary, isGogFileArg, MIN_GOG_VERSION } from './runner.js';
 // Sub-package tools that read gog JSON through bare `run()` (rather than the
 // `runOrDiagnose` seam) must still apply this, or their timestamps skip the

package/src/send-confirm-token.ts

@@ -0,0 +1,167 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { readEnvVar } from '@chrischall/mcp-utils';
+
+// ============================================================================
+// THE TOKEN FALLBACK for the Gmail dispatch rail (gmail-dispatch-guard.ts).
+//
+// 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.
+//
+// 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.
+// ============================================================================
+
+export type ConfirmTokenError = 'DRAFT_CHANGED' | 'TOKEN_EXPIRED' | 'TOKEN_REUSED' | 'TOKEN_INVALID';
+
+/** 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;
+}
+
+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. */
+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/src/tools/api.ts

@@ -6,6 +6,7 @@ import { assertSafeForwardedArgs } from '../arg-guard.js';
 import { confineAtFile } from '../file-roots.js';
 import { pos } from '../argv.js';
 import type { GogArg } from '../runner.js';
+import { gatedElsewhere } from '../dispatch-confirmation.js';
 
 // Gmail methods gog_api_call refuses outright (audit SEC-2). `allowWrite` is a
 // boolean the MODEL sets, so it cannot stand in for the user's confirmation of
@@ -15,12 +16,32 @@ import type { GogArg } from '../runner.js';
 // the same reason. --gmail-no-send is pinned on as a runtime backstop too.
 const GMAIL_API_BLOCKED = /(?:\.send$|forwarding|filters\.create|filters\.update|delegates\.create)/i;
 
+// The same reasoning for every other action the dispatch rail gates (#400):
+// the dedicated tool asks the user, so the raw API method must not be a way
+// around it. Anchored on a `.` or the start so a Discovery id with the API
+// prefix (`chat.spaces.messages.create`) matches too.
+const DISPATCH_API_BLOCKED: Record<string, Array<{ method: RegExp; does: string; tool: string }>> = {
+  chat: [{ method: /(?:^|\.)spaces\.messages\.create$/i, does: 'posts a Chat message', tool: 'gog_chat_messages_send / gog_chat_dm_send' }],
+  drive: [{ method: /(?:^|\.)permissions\.(?:create|update)$/i, does: 'grants access to a file', tool: 'gog_drive_share' }],
+  classroom: [
+    { method: /(?:^|\.)courses\.announcements\.create$/i, does: 'posts to a class', tool: 'gog_classroom_announcements_create' },
+    { method: /(?:^|\.)invitations\.create$/i, does: 'invites someone to a class', tool: 'gog_classroom_invitations_create' },
+  ],
+  calendar: [
+    { method: /(?:^|\.)events\.(?:insert|import|quickadd)$/i, does: 'can put an event on guests\' calendars', tool: 'gog_calendar_create' },
+    { method: /(?:^|\.)events\.(?:update|patch)$/i, does: 'can change what guests see', tool: 'gog_calendar_update / gog_calendar_respond' },
+  ],
+};
+
 export function refusedApiCall(api: string, method: string): string | undefined {
-  if (api.trim().toLowerCase() === 'gmail' && GMAIL_API_BLOCKED.test(method.trim())) {
+  const name = api.trim().toLowerCase();
+  const m = method.trim();
+  if (name === 'gmail' && GMAIL_API_BLOCKED.test(m)) {
     return `gmail ${method} is not available through gog_api_call: it sends or forwards mail. `
       + 'Use gog_gmail_send / gog_gmail_drafts_send (which ask the user to confirm) or the dedicated gog_gmail_* tool.';
   }
-  return undefined;
+  const hit = (Object.hasOwn(DISPATCH_API_BLOCKED, name) ? DISPATCH_API_BLOCKED[name] : [])!.find((b) => b.method.test(m));
+  return hit ? gatedElsewhere(`${name} ${m}`, 'gog_api_call', hit.does, hit.tool) : undefined;
 }
 
 // Generic Google Discovery API access (gog 0.31). gog_api_list / gog_api_describe
@@ -57,7 +78,7 @@ export function registerApiTools(server: McpServer): void {
   });
 
   server.registerTool('gog_api_call', {
-    description: 'Call any Discovery-described Google API method directly — an escape hatch for endpoints gog has no dedicated tool for. Find the exact api/version/method/params with gog_api_describe first. Read methods (GET/LIST) run as-is. Mutating methods (POST/PUT/PATCH/DELETE) are refused unless you set allowWrite=true — keep it false to preview, or set dryRun=true to print the intended request without sending it. Gmail send and forwarding methods (users.messages.send, users.drafts.send, forwarding/auto-forwarding, filters, delegates) are refused — use the dedicated gog_gmail_* tools, which ask the user to confirm.',
+    description: 'Call any Discovery-described Google API method directly — an escape hatch for endpoints gog has no dedicated tool for. Find the exact api/version/method/params with gog_api_describe first. Read methods (GET/LIST) run as-is. Mutating methods (POST/PUT/PATCH/DELETE) are refused unless you set allowWrite=true — keep it false to preview, or set dryRun=true to print the intended request without sending it. Gmail send and forwarding methods (users.messages.send, users.drafts.send, forwarding/auto-forwarding, filters, delegates) are refused — use the dedicated gog_gmail_* tools, which ask the user to confirm. So are the other methods a dedicated tool asks about: Chat spaces.messages.create, Drive permissions.create/update, Classroom courses.announcements.create and invitations.create, and Calendar events.insert/import/quickAdd/update/patch.',
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       api: z.string().describe('Discovery API name (e.g. drive, gmail, calendar)'),