gogcli-mcp 4.3.0 → 4.4.0

package/src/tools/calendar.ts

@@ -5,6 +5,23 @@ import { accountParam, runOrDiagnose, registerRunTool, pageTokenParam, pageAlias
 import { annotateTruncatedList } from '../pagination.js';
 import { pos } from '../argv.js';
 import type { GogArg } from '../runner.js';
+import { CONFIRM_FALLBACK_DESCRIPTION, confirmTokenParam, gatedElsewhere, requireDispatchConfirmation, resultText } from '../dispatch-confirmation.js';
+
+// gog's spellings (internal/cmd/calendar.go). The run tool cannot tell whether
+// an event has guests, so it refuses these outright; the dedicated tools ask
+// only when someone else would see the change.
+const CALENDAR_GATED: Record<string, string> = {
+  create: 'gog_calendar_create', add: 'gog_calendar_create', new: 'gog_calendar_create',
+  update: 'gog_calendar_update', edit: 'gog_calendar_update', set: 'gog_calendar_update',
+  respond: 'gog_calendar_respond', rsvp: 'gog_calendar_respond', reply: 'gog_calendar_respond',
+};
+
+/** gog_calendar_run must not make the changes gog_calendar_create/update/respond would ask about. */
+export function vetCalendarRun(subcommand: string, _args: readonly string[]): string | undefined {
+  const sub = subcommand.toLowerCase();
+  const tool = Object.hasOwn(CALENDAR_GATED, sub) ? CALENDAR_GATED[sub] : undefined;
+  return tool ? gatedElsewhere(`gog calendar ${sub}`, 'gog_calendar_run', 'can change what guests see', tool) : undefined;
+}
 
 // Reminder params, shared by create and update (gog >= 0.38.0 for
 // --no-reminders). An event's reminders are one of THREE states, and the two
@@ -20,6 +37,72 @@ import type { GogArg } from '../runner.js';
 // the flag (leave whatever the event already has) and from --no-reminders
 // (override the calendar with silence). An empty array is how a JSON caller
 // says it, since there is no way to send a bare flag with no value.
+// ============================================================================
+// GUEST-VISIBLE CHANGES go through the dispatch rail. gog sends no invitation
+// email here (its --send-updates defaults to none and these tools never pass
+// it), but a guest still sees the event appear, move or change on their own
+// calendar, and an organizer sees a response. A change nobody else can see — a
+// guest-free event, or a reminder, which is per-user — is not gated.
+// ============================================================================
+
+/** The emails in an attendees flag value (`a@x.com;optional,b@y.com;resource`), resources excluded. */
+export function parseAttendees(value: string | undefined): string[] {
+  if (!value) return [];
+  return value.split(',')
+    .map((entry) => entry.split(';'))
+    .filter((parts) => !parts.slice(1).some((m) => m.trim().toLowerCase() === 'resource'))
+    .map((parts) => parts[0]!.trim())
+    .filter(Boolean);
+}
+
+type EventAttendee = { email?: unknown; self?: unknown; resource?: unknown };
+type EventTime = { dateTime?: unknown; date?: unknown };
+
+function timeOf(t: EventTime | undefined): string | undefined {
+  const v = t?.dateTime ?? t?.date;
+  return typeof v === 'string' ? v : undefined;
+}
+
+/** What a calendar dispatch's prompt shows about the event as it stands now. */
+export function eventSnapshot(raw: string): {
+  summary?: string;
+  start?: string;
+  end?: string;
+  organizer?: string;
+  guests: string[];
+  etag?: string;
+} {
+  let event: {
+    summary?: unknown; start?: EventTime; end?: EventTime; etag?: unknown;
+    organizer?: { email?: unknown }; attendees?: EventAttendee[];
+  } | undefined;
+  try {
+    event = (JSON.parse(raw) as { event?: typeof event } | null)?.event;
+  } catch {
+    event = undefined;
+  }
+  const str = (v: unknown) => (typeof v === 'string' ? v : undefined);
+  return {
+    summary: str(event?.summary),
+    start: timeOf(event?.start),
+    end: timeOf(event?.end),
+    organizer: str(event?.organizer?.email),
+    // Guests are the OTHER people: not this account's own attendee row, not rooms.
+    guests: (Array.isArray(event?.attendees) ? event.attendees : [])
+      .filter((a) => a.self !== true && a.resource !== true && typeof a.email === 'string')
+      .map((a) => a.email as string),
+    etag: str(event?.etag),
+  };
+}
+
+async function readEvent(calendarId: string, eventId: string, account: string | undefined) {
+  const got = await runOrDiagnose(['calendar', 'event', pos(calendarId), pos(eventId)], { account });
+  if (got.isError) return { error: got };
+  return { event: eventSnapshot(resultText(got)) };
+}
+
+const CALENDAR_CONFIRM_LABEL = 'Confirm that this change, which other people will see, should be made now.';
+
 const reminderParams = {
   reminders: z.array(z.string()).max(5).optional().describe(
     'Reminders as method:duration, e.g. ["popup:30m", "email:1d"]. Method is popup or email; duration accepts m/h/d '
@@ -149,7 +232,10 @@ export function registerCalendarTools(server: McpServer): void {
   });
 
   server.registerTool('gog_calendar_create', {
-    description: 'Create a calendar event. Set withZoom=true to attach a Zoom meeting (requires Zoom S2S OAuth setup via gog_zoom_auth_setup; the join URL + meeting ID + passcode are appended to the event description — Google rejects native conference card writes from non-Workspace-Marketplace OAuth clients).',
+    description: 'Create a calendar event. Set withZoom=true to attach a Zoom meeting (requires Zoom S2S OAuth setup via gog_zoom_auth_setup; the join URL + meeting ID + passcode are appended to the event description — Google rejects native conference card writes from non-Workspace-Marketplace OAuth clients). '
+      + 'With attendees, the event lands on other people\'s calendars (no invitation email is sent), so the MCP host is '
+      + 'asked to show the user a confirmation prompt with the guests, time and details first; a guest-free event is '
+      + 'created without asking.' + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: false },
     inputSchema: z.object({
       calendarId: z.string().describe('Calendar ID (use "primary" for the default calendar)'),
@@ -164,8 +250,9 @@ export function registerCalendarTools(server: McpServer): void {
       withZoom: z.boolean().optional().describe('Create a Zoom video conference for this event (requires Zoom S2S OAuth setup)'),
       ...reminderParams,
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ calendarId, summary, from, to, description, location, attendees, allDay, timezone, withZoom, reminders, noReminders, account }) => {
+  }, async ({ calendarId, summary, from, to, description, location, attendees, allDay, timezone, withZoom, reminders, noReminders, account, confirmToken }, ctx) => {
     const args: GogArg[] = ['calendar', 'create', pos(calendarId), `--summary=${summary}`, `--from=${from}`, `--to=${to}`];
     if (description) args.push(`--description=${description}`);
     if (location) args.push(`--location=${location}`);
@@ -174,11 +261,33 @@ export function registerCalendarTools(server: McpServer): void {
     if (timezone) args.push(`--timezone=${timezone}`);
     if (withZoom) args.push('--with-zoom');
     pushReminderFlags(args, { reminders, noReminders });
+    const guests = parseAttendees(attendees);
+    if (guests.length > 0) {
+      const event = { calendarId, summary, from, to, allDay: Boolean(allDay), timezone, location, description, guests, attendees, withZoom: Boolean(withZoom) };
+      const confirmation = await requireDispatchConfirmation(ctx, {
+        action: 'calendar.create',
+        message: 'Review and confirm this event, which will appear on the guests\' calendars:',
+        confirmationLabel: CALENDAR_CONFIRM_LABEL,
+        details: event,
+        unsupportedNote: 'Create it without attendees instead; the user can add the guests in Google Calendar.',
+        fallback: {
+          tool: 'gog_calendar_create',
+          account,
+          confirmToken,
+          subject: () => ({ target: calendarId, payload: event, preview: event }),
+        },
+      });
+      if (confirmation) return confirmation;
+    }
     return runOrDiagnose(args, { account });
   });
 
   server.registerTool('gog_calendar_update', {
-    description: 'Update an existing calendar event. Zoom: withZoom adds a Zoom meeting, regenerateZoom replaces the existing one, removeZoom strips it. removeMeet clears the event\'s Google Meet conference data (e.g. before attaching another provider). Conference flags are independent — use one per call.',
+    description: 'Update an existing calendar event. Zoom: withZoom adds a Zoom meeting, regenerateZoom replaces the existing one, removeZoom strips it. removeMeet clears the event\'s Google Meet conference data (e.g. before attaching another provider). Conference flags are independent — use one per call. '
+      + 'A change guests can see (time, title, place, description, attendees, attachments, conferencing) on an event '
+      + 'that has guests — or gains them — reads the event and asks the MCP host to show the user a confirmation prompt '
+      + 'with the event as it stands and the change; no invitation email is sent. Reminder-only changes and guest-free '
+      + 'events are updated without asking.' + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: false },
     inputSchema: z.object({
       calendarId: z.string().describe('Calendar ID'),
@@ -197,8 +306,9 @@ export function registerCalendarTools(server: McpServer): void {
       removeMeet: z.boolean().optional().describe('Remove the event\'s Google Meet video conference (clears conference data only)'),
       ...reminderParams,
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ calendarId, eventId, summary, from, to, description, location, attendees, addAttendees, attachments, withZoom, regenerateZoom, removeZoom, removeMeet, reminders, noReminders, account }) => {
+  }, async ({ calendarId, eventId, summary, from, to, description, location, attendees, addAttendees, attachments, withZoom, regenerateZoom, removeZoom, removeMeet, reminders, noReminders, account, confirmToken }, ctx) => {
     const args: GogArg[] = ['calendar', 'update', pos(calendarId), pos(eventId)];
     if (summary !== undefined) args.push(`--summary=${summary}`);
     if (from !== undefined) args.push(`--from=${from}`);
@@ -213,6 +323,36 @@ export function registerCalendarTools(server: McpServer): void {
     if (removeZoom) args.push('--remove-zoom');
     if (removeMeet) args.push('--remove-meet');
     pushReminderFlags(args, { reminders, noReminders });
+    // Every field guests can see; reminders are per-user and are not on it.
+    const changes = Object.fromEntries(Object.entries({
+      summary, from, to, description, location, attendees, addAttendees, attachments,
+      withZoom, regenerateZoom, removeZoom, removeMeet,
+    }).filter(([, v]) => v !== undefined && v !== false));
+    if (Object.keys(changes).length > 0) {
+      const read = await readEvent(calendarId, eventId, account);
+      if (read.error) return read.error;
+      const { etag, ...current } = read.event;
+      const added = [...parseAttendees(attendees), ...parseAttendees(addAttendees)];
+      if (current.guests.length > 0 || added.length > 0) {
+        const view = { calendarId, eventId, current, changes };
+        const confirmation = await requireDispatchConfirmation(ctx, {
+          action: 'calendar.update',
+          message: 'Review and confirm this change to an event other people are on:',
+          confirmationLabel: CALENDAR_CONFIRM_LABEL,
+          details: view,
+          unsupportedNote: 'Ask the user to make this change in Google Calendar.',
+          fallback: {
+            tool: 'gog_calendar_update',
+            account,
+            confirmToken,
+            // The etag rotates on any edit, so an event changed elsewhere between
+            // the two phases is DRAFT_CHANGED rather than edited over.
+            subject: () => ({ target: `${calendarId}/${eventId}`, revision: etag, payload: view, preview: view }),
+          },
+        });
+        if (confirmation) return confirmation;
+      }
+    }
     return runOrDiagnose(args, { account });
   });
 
@@ -231,7 +371,9 @@ export function registerCalendarTools(server: McpServer): void {
   });
 
   server.registerTool('gog_calendar_respond', {
-    description: 'Respond to a calendar event invitation.',
+    description: 'Respond to a calendar event invitation. The organizer sees the response, so this reads the event and '
+      + 'asks the MCP host to show the user a confirmation prompt with the event, organizer, response and comment; '
+      + 'nothing is recorded unless they accept.' + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       calendarId: z.string().describe('Calendar ID'),
@@ -239,12 +381,31 @@ export function registerCalendarTools(server: McpServer): void {
       status: z.enum(['accepted', 'declined', 'tentative']).describe('Response status'),
       comment: z.string().optional().describe('Optional comment to include with response'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ calendarId, eventId, status, comment, account }) => {
+  }, async ({ calendarId, eventId, status, comment, account, confirmToken }, ctx) => {
     const args: GogArg[] = ['calendar', 'respond', pos(calendarId), pos(eventId), `--status=${status}`];
     if (comment) args.push(`--comment=${comment}`);
+    const read = await readEvent(calendarId, eventId, account);
+    if (read.error) return read.error;
+    const { etag, ...event } = read.event;
+    const view = { calendarId, eventId, event, response: status, ...(comment ? { comment } : {}) };
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: 'calendar.respond',
+      message: 'Review and confirm this response, which the organizer will see:',
+      confirmationLabel: 'Confirm that this response should be recorded now.',
+      details: view,
+      unsupportedNote: 'Ask the user to respond from Google Calendar.',
+      fallback: {
+        tool: 'gog_calendar_respond',
+        account,
+        confirmToken,
+        subject: () => ({ target: `${calendarId}/${eventId}`, revision: etag, payload: view, preview: view }),
+      },
+    });
+    if (confirmation) return confirmation;
     return runOrDiagnose(args, { account });
   });
 
-  registerRunTool(server, { service: 'calendar', examples: '"calendars", "freebusy"' });
+  registerRunTool(server, { service: 'calendar', examples: '"calendars", "freebusy"', vet: vetCalendarRun });
 }

package/src/tools/chat.ts

@@ -11,6 +11,38 @@ import type { GogArg } from '../runner.js';
 import { attachInlineParam, inlineAttachmentArgs } from '../attachments.js';
 import { pos } from '../argv.js';
 import { confinePaths } from '../file-roots.js';
+import {
+  attachmentDetails,
+  attachmentNames,
+  attachmentPreview,
+  bodyPreview,
+  CONFIRM_FALLBACK_DESCRIPTION,
+  confirmTokenParam,
+  gatedElsewhere,
+  hasCommandWord,
+  requireDispatchConfirmation,
+  senderPreview,
+} from '../dispatch-confirmation.js';
+
+// gog's spellings of `send` under `messages` and `dm` (internal/cmd/chat_messages.go, chat_dm.go).
+const CHAT_SEND_WORDS = new Set(['send', 'create', 'post']);
+
+/** gog_chat_run must not post what gog_chat_messages_send / gog_chat_dm_send would ask about. */
+export function vetChatRun(subcommand: string, args: readonly string[]): string | undefined {
+  const sub = subcommand.toLowerCase();
+  if (sub !== 'messages' && sub !== 'dm') return undefined;
+  const word = hasCommandWord(args, CHAT_SEND_WORDS);
+  if (!word) return undefined;
+  return gatedElsewhere(`gog chat ${sub} ${word.toLowerCase()}`, 'gog_chat_run', 'posts a message',
+    sub === 'dm' ? 'gog_chat_dm_send' : 'gog_chat_messages_send');
+}
+
+// A Chat post lands in other people's view the moment it is sent and cannot be
+// unsent here, so both send tools go through the dispatch rail like Gmail does.
+const CHAT_CONFIRM = {
+  message: 'Review and confirm this Google Chat message:',
+  confirmationLabel: 'Confirm that this Chat message should be posted now.',
+} as const;
 
 // Google Chat (gog >= 0.38.0 for the mention/reaction metadata in
 // `messages list`, >= 0.39.0 for `messages search`; the rest is older).
@@ -178,7 +210,9 @@ export function registerChatTools(server: McpServer): void {
       'Post a message to a Chat space. THIS IS IMMEDIATELY VISIBLE TO EVERYONE IN THE SPACE and cannot be unsent through '
       + 'this tool, so treat it like sending mail, not like saving a draft. Pass `thread` to reply inside an existing '
       + 'conversation (from gog_chat_threads_list or a message\'s thread field); omit it to start a new one. Text supports '
-      + 'Chat\'s markdown-ish formatting (*bold*, _italic_, `code`).' + workspaceOnlyNote,
+      + 'Chat\'s markdown-ish formatting (*bold*, _italic_, `code`). Asks the MCP host to show the user a confirmation '
+      + 'prompt with the space, thread, text and attachments first; nothing is posted unless they accept.'
+      + CONFIRM_FALLBACK_DESCRIPTION + workspaceOnlyNote,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       space: spaceParam,
@@ -190,8 +224,9 @@ export function registerChatTools(server: McpServer): void {
       ),
       attachInline: attachInlineParam,
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ space, text, thread, attach, attachInline, account }) => {
+  }, async ({ space, text, thread, attach, attachInline, account, confirmToken }, ctx) => {
     confinePaths(attach, 'attach');
     if (text === undefined && !attach?.length && !attachInline?.length) {
       throw new Error('A Chat message needs text, an attachment, or both.');
@@ -204,24 +239,61 @@ export function registerChatTools(server: McpServer): void {
     // a temp file beside gog. `args` is passed so the size check sees the whole
     // request, not just the attachments.
     args.push(...inlineAttachmentArgs('attach', attachInline, args));
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      ...CHAT_CONFIRM,
+      action: 'chat.message-send',
+      details: { space, thread, textPreview: bodyPreview(text), attachments: attachmentNames(attach, attachInline) },
+      fallback: {
+        tool: 'gog_chat_messages_send',
+        account,
+        confirmToken,
+        subject: () => {
+          const attachments = attachmentDetails(attach, attachInline);
+          const from = senderPreview(account);
+          return {
+            target: space,
+            payload: { from, space, thread, text, attachments },
+            preview: { from, space, thread, text, attachments: attachmentPreview(attachments) },
+          };
+        },
+      },
+    });
+    if (confirmation) return confirmation;
     return runOrDiagnose(args, { account });
   });
 
   server.registerTool('gog_chat_dm_send', {
     description:
       'Send a direct message to one person by email address, creating the DM space if this is the first message. Delivered '
-      + 'immediately and cannot be unsent through this tool. For a room rather than a person, use gog_chat_messages_send.'
-      + workspaceOnlyNote,
+      + 'immediately and cannot be unsent through this tool. For a room rather than a person, use gog_chat_messages_send. '
+      + 'Asks the MCP host to show the user a confirmation prompt with the recipient and text first; nothing is sent '
+      + 'unless they accept.' + CONFIRM_FALLBACK_DESCRIPTION + workspaceOnlyNote,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       email: z.string().describe('Recipient email address'),
       text: z.string().describe('Message text'),
       thread: threadParam,
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ email, text, thread, account }) => {
+  }, async ({ email, text, thread, account, confirmToken }, ctx) => {
     const args: GogArg[] = ['chat', 'dm', 'send', pos(email), `--text=${text}`];
     if (thread) args.push(`--thread=${thread}`);
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      ...CHAT_CONFIRM,
+      action: 'chat.dm-send',
+      details: { to: email, thread, textPreview: bodyPreview(text) },
+      fallback: {
+        tool: 'gog_chat_dm_send',
+        account,
+        confirmToken,
+        subject: () => {
+          const from = senderPreview(account);
+          return { target: email, payload: { from, to: email, thread, text }, preview: { from, to: email, thread, text } };
+        },
+      },
+    });
+    if (confirmation) return confirmation;
     return runOrDiagnose(args, { account });
   });
 
@@ -291,6 +363,7 @@ export function registerChatTools(server: McpServer): void {
   registerRunTool(server, {
     service: 'chat',
     examples: '"spaces", "messages", "dm"',
+    vet: vetChatRun,
     note: 'Google Chat has no API for consumer accounts: every chat subcommand fails on an @gmail.com account regardless of scopes.',
   });
 }

package/src/tools/classroom.ts

@@ -3,6 +3,57 @@ import { z } from 'zod';
 import { accountParam, runOrDiagnose, registerRunTool, pageTokenParam, pageAliasParam, resolvePageToken} from './utils.js';
 import { pos } from '../argv.js';
 import type { GogArg } from '../runner.js';
+import { bodyPreview, CONFIRM_FALLBACK_DESCRIPTION, confirmTokenParam, gatedElsewhere, hasCommandWord, requireDispatchConfirmation, resultText } from '../dispatch-confirmation.js';
+
+// gog's spellings (internal/cmd/classroom.go, classroom_announcements.go, classroom_invitations.go).
+const CLASSROOM_CREATE_WORDS = new Set(['create', 'add', 'new']);
+const CLASSROOM_GATED: Record<string, { does: string; tool: string }> = {
+  announcements: { does: 'posts to a class', tool: 'gog_classroom_announcements_create' },
+  announcement: { does: 'posts to a class', tool: 'gog_classroom_announcements_create' },
+  ann: { does: 'posts to a class', tool: 'gog_classroom_announcements_create' },
+  invitations: { does: 'invites someone to a class', tool: 'gog_classroom_invitations_create' },
+  invitation: { does: 'invites someone to a class', tool: 'gog_classroom_invitations_create' },
+  invites: { does: 'invites someone to a class', tool: 'gog_classroom_invitations_create' },
+};
+
+/** gog_classroom_run must not post or invite what the dedicated tools would ask about. */
+export function vetClassroomRun(subcommand: string, args: readonly string[]): string | undefined {
+  const sub = subcommand.toLowerCase();
+  const gated = Object.hasOwn(CLASSROOM_GATED, sub) ? CLASSROOM_GATED[sub] : undefined;
+  if (!gated) return undefined;
+  const word = hasCommandWord(args, CLASSROOM_CREATE_WORDS);
+  return word ? gatedElsewhere(`gog classroom ${sub} ${word.toLowerCase()}`, 'gog_classroom_run', gated.does, gated.tool) : undefined;
+}
+
+/**
+ * The course a Classroom dispatch reaches, for its confirmation prompt: a user
+ * approving "post to 123456789" cannot tell which class that is. Read on every
+ * call, so it is also the token fallback's phase-2 re-read. Unreadable output
+ * names nothing rather than throwing.
+ */
+export async function readCourse(
+  courseId: string,
+  account: string | undefined,
+  // A sub-package passes the runOrDiagnose it imported from lib.js, so its own
+  // tests' mock of that seam covers this read too.
+  runner: typeof runOrDiagnose = runOrDiagnose,
+) {
+  const got = await runner(['classroom', 'courses', 'get', pos(courseId)], { account });
+  if (got.isError) return { error: got };
+  let course: { name?: unknown; section?: unknown } | undefined;
+  try {
+    course = (JSON.parse(resultText(got)) as { course?: typeof course } | null)?.course;
+  } catch {
+    course = undefined;
+  }
+  return {
+    course: {
+      id: courseId,
+      ...(typeof course?.name === 'string' ? { name: course.name } : {}),
+      ...(typeof course?.section === 'string' ? { section: course.section } : {}),
+    },
+  };
+}
 
 export function registerClassroomTools(server: McpServer): void {
   server.registerTool('gog_classroom_courses_list', {
@@ -303,19 +354,47 @@ export function registerClassroomTools(server: McpServer): void {
   });
 
   server.registerTool('gog_classroom_announcements_create', {
-    description: 'Create an announcement in a Google Classroom course.',
+    description: 'Create an announcement in a Google Classroom course. Unless state is DRAFT (which students cannot '
+      + 'see), this reads the course and asks the MCP host to show the user a confirmation prompt with the class, the '
+      + 'full text and when it publishes; nothing is posted unless they accept. To stage one without asking, pass '
+      + 'state DRAFT.' + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       courseId: z.string().describe('Course ID'),
       text: z.string().describe('Announcement text'),
-      state: z.enum(['PUBLISHED', 'DRAFT']).optional().describe('State'),
+      state: z.enum(['PUBLISHED', 'DRAFT']).optional().describe('State (DRAFT is visible only to teachers and needs no confirmation)'),
       scheduled: z.string().optional().describe('Scheduled publish time'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ courseId, text, state, scheduled, account }) => {
+  }, async ({ courseId, text, state, scheduled, account, confirmToken }, ctx) => {
     const args: GogArg[] = ['classroom', 'announcements', 'create', pos(courseId), `--text=${text}`];
     if (state) args.push(`--state=${state}`);
     if (scheduled) args.push(`--scheduled=${scheduled}`);
+    // A draft reaches nobody until a teacher publishes it: it is this tool's
+    // own staging twin, so it needs no confirmation.
+    if (state !== 'DRAFT') {
+      const read = await readCourse(courseId, account);
+      if (read.error) return read.error;
+      const publishes = scheduled ? `at ${scheduled}` : 'immediately';
+      const confirmation = await requireDispatchConfirmation(ctx, {
+        action: 'classroom.announcement-create',
+        message: 'Review and confirm this Classroom announcement:',
+        confirmationLabel: 'Confirm that this announcement should be posted to the class.',
+        details: { course: read.course, publishes, textPreview: bodyPreview(text) },
+        unsupportedNote: 'Create it with state DRAFT instead; the user can review and post it from Classroom.',
+        fallback: {
+          tool: 'gog_classroom_announcements_create',
+          account,
+          confirmToken,
+          subject: () => {
+            const view = { course: read.course, publishes, text };
+            return { target: courseId, payload: view, preview: view };
+          },
+        },
+      });
+      if (confirmation) return confirmation;
+    }
     return runOrDiagnose(args, { account });
   });
 
@@ -412,6 +491,7 @@ export function registerClassroomTools(server: McpServer): void {
   registerRunTool(server, {
     service: 'classroom',
     examples: '"guardians", "materials", "guardian-invitations"',
+    vet: vetClassroomRun,
     note: 'Covers anything not wrapped by the dedicated tools (guardians, guardian-invitations, materials, coursework assignees, announcement assignees, etc.).',
   });
 }

package/src/tools/drive.ts

@@ -8,6 +8,14 @@ import { run, runBinary } from '../runner.js';
 import { accountParam, diagnose, runOrDiagnose, registerRunTool, pageTokenParam, pageAliasParam, resolvePageToken} from './utils.js';
 import { pos } from '../argv.js';
 import type { GogArg } from '../runner.js';
+import { CONFIRM_FALLBACK_DESCRIPTION, confirmTokenParam, gatedElsewhere, requireDispatchConfirmation, resultText } from '../dispatch-confirmation.js';
+
+/** gog_drive_run must not grant access that gog_drive_share would ask about. */
+export function vetDriveRun(subcommand: string, _args: readonly string[]): string | undefined {
+  return subcommand.toLowerCase() === 'share'
+    ? gatedElsewhere('gog drive share', 'gog_drive_run', 'grants access to a file', 'gog_drive_share')
+    : undefined;
+}
 
 // A native Google Doc exports to text directly; anything else (PDF, image,
 // docx, …) is first copied WITH conversion to this type, which makes Drive run
@@ -18,6 +26,16 @@ const GOOGLE_DOC_MIME = 'application/vnd.google-apps.document';
 // under `file`; fall back to the top level if that ever changes.
 type DriveMeta = { name?: string; mimeType?: string; size?: string | number };
 
+/** fileMeta for a preview: unreadable output names nothing rather than throwing. */
+export function shareTargetMeta(raw: string): { name?: string; mimeType?: string } {
+  try {
+    const { name, mimeType } = fileMeta(raw);
+    return { name, mimeType };
+  } catch {
+    return {};
+  }
+}
+
 function fileMeta(raw: string): { name?: string; mimeType?: string; size?: number } {
   const parsed = JSON.parse(raw) as { file?: DriveMeta } & DriveMeta;
   const f = parsed.file ?? parsed;
@@ -170,7 +188,10 @@ export function registerDriveTools(server: McpServer): void {
   });
 
   server.registerTool('gog_drive_share', {
-    description: 'Share a Google Drive file or folder.',
+    description: 'Share a Google Drive file or folder. Granting access is the risk even though no email is sent (gog '
+      + 'does not notify by default), so this reads the file and asks the MCP host to show the user a confirmation '
+      + 'prompt naming it, who gets access and with what role; nothing is shared unless they accept.'
+      + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       fileId: z.string().describe('File or folder ID'),
@@ -179,8 +200,39 @@ export function registerDriveTools(server: McpServer): void {
       domain: z.string().optional().describe('Domain (required when to=domain)'),
       role: z.enum(['reader', 'writer']).optional().describe('Permission role (default: reader)'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ fileId, to, email, domain, role, account }) => {
+  }, async ({ fileId, to, email, domain, role, account, confirmToken }, ctx) => {
+    // Read first, on every call: a prompt that shows only an opaque id asks the
+    // user to approve something they cannot recognise, and on the token
+    // fallback's phase 2 this is the re-read the token is checked against.
+    const got = await runOrDiagnose(['drive', 'get', pos(fileId)], { account });
+    if (got.isError) return got;
+    const file = { id: fileId, ...shareTargetMeta(resultText(got)) };
+    const grant = {
+      file,
+      to,
+      ...(email ? { email } : {}),
+      ...(domain ? { domain } : {}),
+      role: role ?? 'reader',
+      publicLink: to === 'anyone',
+    };
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: 'drive.share',
+      message: to === 'anyone'
+        ? 'Review and confirm making this file available to ANYONE with the link:'
+        : 'Review and confirm this Drive share:',
+      confirmationLabel: 'Confirm that this access should be granted now.',
+      details: grant,
+      unsupportedNote: 'Ask the user to share it themselves from Google Drive.',
+      fallback: {
+        tool: 'gog_drive_share',
+        account,
+        confirmToken,
+        subject: () => ({ target: fileId, payload: grant, preview: grant }),
+      },
+    });
+    if (confirmation) return confirmation;
     const args: GogArg[] = ['drive', 'share', pos(fileId), `--to=${to}`];
     if (email) args.push(`--email=${email}`);
     if (domain) args.push(`--domain=${domain}`);
@@ -314,5 +366,5 @@ export function registerDriveTools(server: McpServer): void {
     }
   });
 
-  registerRunTool(server, { service: 'drive', examples: '"copy", "download", "permissions"' });
+  registerRunTool(server, { service: 'drive', examples: '"copy", "download", "permissions"', vet: vetDriveRun });
 }