gogcli-mcp 4.4.0 → 4.5.1

package/src/tools/classroom.ts

@@ -3,26 +3,105 @@ 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';
+import { bodyPreview, CONFIRM_FALLBACK_DESCRIPTION, confirmTokenParam, flagValue, gatedElsewhere, hasCommandWord, refusedInRun, requireDispatchConfirmation, resultText } from '../dispatch-confirmation.js';
 
-// gog's spellings (internal/cmd/classroom.go, classroom_announcements.go, classroom_invitations.go).
+// gog's spellings (internal/cmd/classroom*.go; aliases per `gog schema` 0.41.0),
+// each alias mapped to the resource it names.
 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' },
+const CLASSROOM_DELETE_WORDS = new Set(['delete', 'rm', 'del', 'remove']);
+const CLASSROOM_UPDATE_WORDS = new Set(['update', 'edit', 'set']);
+const CLASSROOM_RETURN_WORDS = new Set(['return', 'send']);
+const CLASSROOM_ASSIGNEE_WORDS = new Set(['assignees', 'assign']);
+type ClassroomGroup = 'courses' | 'announcements' | 'invitations' | 'coursework' | 'materials' | 'students' | 'teachers' | 'submissions' | 'guardian-invitations';
+const CLASSROOM_GROUPS: Record<string, ClassroomGroup> = {
+  courses: 'courses', course: 'courses',
+  announcements: 'announcements', announcement: 'announcements', ann: 'announcements',
+  invitations: 'invitations', invitation: 'invitations', invites: 'invitations',
+  coursework: 'coursework', work: 'coursework',
+  materials: 'materials', material: 'materials',
+  students: 'students', student: 'students',
+  teachers: 'teachers', teacher: 'teachers',
+  submissions: 'submissions', submission: 'submissions',
+  'guardian-invitations': 'guardian-invitations', 'guardian-invites': 'guardian-invitations',
 };
 
-/** gog_classroom_run must not post or invite what the dedicated tools would ask about. */
+/**
+ * True when forwarded flags publish existing work to students: state
+ * PUBLISHED publishes now; a schedule publishes then (a scheduled item is a
+ * draft that publishes itself). A text edit or a return to DRAFT is neither.
+ */
+function publishesToStudents(args: readonly string[]): boolean {
+  return flagValue(args, 'state')?.toUpperCase() === 'PUBLISHED' || flagValue(args, 'scheduled') !== undefined;
+}
+
+/** True when a create reaches students: anything but an unscheduled DRAFT (gog's default state is PUBLISHED). */
+function createsVisibleWork(args: readonly string[]): boolean {
+  return flagValue(args, 'state')?.toUpperCase() !== 'DRAFT' || flagValue(args, 'scheduled') !== undefined;
+}
+
+/** True when an assignees change shows an item to more students: ALL_STUDENTS or an added student. Removing students only narrows it. */
+function widensAssignees(args: readonly string[]): boolean {
+  return flagValue(args, 'mode')?.toUpperCase() === 'ALL_STUDENTS' || flagValue(args, 'add-student') !== undefined;
+}
+
+/**
+ * gog_classroom_run must not post, publish, enrol, return or invite what the
+ * dedicated tools would ask about (#400; SEC-3, fleet-audit #932; SEC-6).
+ * Publishing through `update --state=PUBLISHED` was the two-step around the
+ * create gate that closed for Gmail drafts, so the update words are vetted on
+ * their flags. Deletes that destroy a course or coursework (and every
+ * submission to it) go to the tools that ask first.
+ */
 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;
+  if (!Object.hasOwn(CLASSROOM_GROUPS, sub)) return undefined;
+  const group = CLASSROOM_GROUPS[sub]!;
+  const via = 'gog_classroom_run';
+  const what = (word: string) => `gog classroom ${sub} ${word.toLowerCase()}`;
+  const create = hasCommandWord(args, CLASSROOM_CREATE_WORDS);
+  const update = hasCommandWord(args, CLASSROOM_UPDATE_WORDS);
+  const remove = hasCommandWord(args, CLASSROOM_DELETE_WORDS);
+  const widenedAssignees = (): string | undefined => {
+    const word = hasCommandWord(args, CLASSROOM_ASSIGNEE_WORDS);
+    return word && widensAssignees(args)
+      ? refusedInRun(what(word), via, 'shows it to more students', 'Ask the user to change who it is assigned to from Classroom.')
+      : undefined;
+  };
+  switch (group) {
+    case 'courses':
+      return remove ? gatedElsewhere(what(remove), via, 'deletes a course', 'gog_classroom_courses_delete') : undefined;
+    case 'announcements':
+      if (create) return gatedElsewhere(what(create), via, 'posts to a class', 'gog_classroom_announcements_create');
+      if (update && publishesToStudents(args)) return gatedElsewhere(what(update), via, 'publishes an announcement to a class', 'gog_classroom_announcements_update');
+      return widenedAssignees();
+    case 'invitations':
+      return create ? gatedElsewhere(what(create), via, 'invites someone to a class', 'gog_classroom_invitations_create') : undefined;
+    case 'coursework':
+      // An unscheduled DRAFT reaches nobody, and gog_classroom_coursework_create
+      // does not ask about one either; publishing it later is the update below.
+      if (create && createsVisibleWork(args)) return gatedElsewhere(what(create), via, 'posts coursework to a class', 'gog_classroom_coursework_create');
+      if (remove) return gatedElsewhere(what(remove), via, 'deletes coursework and every submission to it', 'gog_classroom_coursework_delete');
+      if (update && publishesToStudents(args)) return gatedElsewhere(what(update), via, 'publishes work to students', 'gog_classroom_coursework_update');
+      return widenedAssignees();
+    case 'materials':
+      // No dedicated tool updates materials, so publishing one is refused
+      // outright rather than sent to a gated tool.
+      if (create && createsVisibleWork(args)) {
+        return refusedInRun(what(create), via, 'publishes material to students', 'Create it with --state=DRAFT and no --scheduled; ask the user to publish it from Classroom.');
+      }
+      if (update && publishesToStudents(args)) return refusedInRun(what(update), via, 'publishes material to students', 'Ask the user to publish it from Classroom.');
+      return undefined;
+    case 'students':
+      return create ? gatedElsewhere(what(create), via, 'enrols someone in a class', 'gog_classroom_students_add') : undefined;
+    case 'teachers':
+      return create ? gatedElsewhere(what(create), via, "gives someone a teacher's access to a class and its roster", 'gog_classroom_teachers_add') : undefined;
+    case 'submissions': {
+      const word = hasCommandWord(args, CLASSROOM_RETURN_WORDS);
+      return word ? gatedElsewhere(what(word), via, 'returns work to a student, who is notified', 'gog_classroom_submissions_return') : undefined;
+    }
+    case 'guardian-invitations':
+      return create ? refusedInRun(what(create), via, 'emails a guardian invitation', 'Ask the user to invite the guardian from Classroom.') : undefined;
+  }
 }
 
 /**
@@ -55,6 +134,127 @@ export async function readCourse(
   };
 }
 
+/** JSON object under `key` in a gog result, or undefined for unreadable output. */
+function nested(raw: string, key: string): Record<string, unknown> | undefined {
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown> | null;
+    const inner = parsed?.[key];
+    return inner && typeof inner === 'object' ? inner as Record<string, unknown> : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const str = (v: unknown) => (typeof v === 'string' ? v : undefined);
+const num = (v: unknown) => (typeof v === 'number' ? v : undefined);
+
+/** The coursework a Classroom dispatch touches, by title. Same contract as {@link readCourse}. */
+export async function readCoursework(
+  courseId: string,
+  courseworkId: string,
+  account: string | undefined,
+  runner: typeof runOrDiagnose = runOrDiagnose,
+) {
+  const got = await runner(['classroom', 'coursework', 'get', pos(courseId), pos(courseworkId)], { account });
+  if (got.isError) return { error: got };
+  const work = nested(resultText(got), 'coursework');
+  const title = str(work?.title);
+  return { coursework: { id: courseworkId, ...(title !== undefined ? { title } : {}) } };
+}
+
+/** The Classroom items a publish-through-update reaches students with. */
+export type ClassroomWorkKind = 'announcements' | 'coursework';
+
+/** What {@link readClassroomWork} names about an item; each field only when gog returned it as a string. */
+export interface ClassroomWork {
+  id: string;
+  text?: string;
+  title?: string;
+  description?: string;
+  state?: string;
+  updateTime?: string;
+}
+
+/**
+ * The announcement or coursework a publish reaches students with, for its
+ * confirmation prompt (the text, or the title and description: a user
+ * approving "publish a1" cannot tell what a1 says) and as the token fallback's
+ * revision (updateTime rotates on every edit, so an approval never publishes
+ * text it did not name). Read on every call. gog 0.41.0 nests the payload
+ * under `announcement` or `coursework` (internal/cmd/classroom_*.go; not the
+ * API's `courseWork`); unreadable output names nothing rather than throwing.
+ */
+export async function readClassroomWork(
+  kind: ClassroomWorkKind,
+  courseId: string,
+  itemId: string,
+  account: string | undefined,
+  // A sub-package passes the runOrDiagnose it imported from lib.js (see readCourse).
+  runner: typeof runOrDiagnose = runOrDiagnose,
+): Promise<{ error: Awaited<ReturnType<typeof runOrDiagnose>>; work?: undefined } | { error?: undefined; work: ClassroomWork }> {
+  const got = await runner(['classroom', kind, 'get', pos(courseId), pos(itemId)], { account });
+  if (got.isError) return { error: got };
+  const item = nested(resultText(got), kind === 'announcements' ? 'announcement' : 'coursework');
+  const work: ClassroomWork = { id: itemId };
+  for (const key of ['text', 'title', 'description', 'state', 'updateTime'] as const) {
+    const value = str(item?.[key]);
+    if (value !== undefined) work[key] = value;
+  }
+  return { work };
+}
+
+/**
+ * A submission as a return's prompt shows it — whose it is, its state and
+ * grades — plus its `updateTime` apart, as the token fallback's revision: a
+ * submission re-graded between the phases is DRAFT_CHANGED, not returned with a
+ * grade the user never saw.
+ */
+export async function readSubmission(
+  courseId: string,
+  courseworkId: string,
+  submissionId: string,
+  account: string | undefined,
+  runner: typeof runOrDiagnose = runOrDiagnose,
+) {
+  const got = await runner(['classroom', 'submissions', 'get', pos(courseId), pos(courseworkId), pos(submissionId)], { account });
+  if (got.isError) return { error: got };
+  const sub = nested(resultText(got), 'submission');
+  const fields = {
+    student: str(sub?.userId),
+    state: str(sub?.state),
+    draftGrade: num(sub?.draftGrade),
+    assignedGrade: num(sub?.assignedGrade),
+  };
+  const updateTime = str(sub?.updateTime);
+  return {
+    submission: {
+      id: submissionId,
+      ...Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined)),
+    } as { id: string; student?: string; state?: string; draftGrade?: number; assignedGrade?: number },
+    ...(updateTime !== undefined ? { updateTime } : {}),
+  };
+}
+
+/**
+ * A person on a course roster by name and email, for a prompt that would
+ * otherwise show only a numeric user id. Best effort: an unreadable or failed
+ * read falls back to the id the caller has.
+ */
+export async function studentLabel(
+  courseId: string,
+  userId: string,
+  account: string | undefined,
+  runner: typeof runOrDiagnose = runOrDiagnose,
+): Promise<string> {
+  const got = await runner(['classroom', 'students', 'get', pos(courseId), pos(userId)], { account });
+  if (got.isError) return userId;
+  const profile = nested(resultText(got), 'student')?.profile as { name?: { fullName?: unknown }; emailAddress?: unknown } | undefined;
+  const name = str(profile?.name?.fullName);
+  const email = str(profile?.emailAddress);
+  if (name && email) return `${name} <${email}>`;
+  return name ?? email ?? userId;
+}
+
 export function registerClassroomTools(server: McpServer): void {
   server.registerTool('gog_classroom_courses_list', {
     description: 'List Google Classroom courses.',
@@ -279,15 +479,43 @@ export function registerClassroomTools(server: McpServer): void {
   });
 
   server.registerTool('gog_classroom_submissions_return', {
-    description: 'Return a graded submission to the student.',
+    description: 'Return a graded submission to the student, who is notified and sees the grade. Reads the course, the '
+      + 'coursework and the submission and asks the MCP host to show the user a confirmation prompt with the class, the '
+      + 'assignment, the student and the grade being returned; nothing is returned unless they accept.'
+      + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       courseId: z.string().describe('Course ID'),
       courseworkId: z.string().describe('Coursework ID'),
       submissionId: z.string().describe('Submission ID'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ courseId, courseworkId, submissionId, account }) => {
+  }, async ({ courseId, courseworkId, submissionId, account, confirmToken }, ctx) => {
+    const course = await readCourse(courseId, account);
+    if (course.error) return course.error;
+    const work = await readCoursework(courseId, courseworkId, account);
+    if (work.error) return work.error;
+    const sub = await readSubmission(courseId, courseworkId, submissionId, account);
+    if (sub.error) return sub.error;
+    const submission = sub.submission.student
+      ? { ...sub.submission, student: await studentLabel(courseId, sub.submission.student, account) }
+      : sub.submission;
+    const view = { course: course.course, coursework: work.coursework, submission };
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: 'classroom.submission-return',
+      message: 'Review and confirm returning this work — the student is notified and sees the grade:',
+      confirmationLabel: 'Confirm that this submission should be returned to the student now.',
+      details: view,
+      unsupportedNote: 'Ask the user to return it from Classroom.',
+      fallback: {
+        tool: 'gog_classroom_submissions_return',
+        account,
+        confirmToken,
+        subject: () => ({ target: `${courseId}/${courseworkId}/${submissionId}`, revision: sub.updateTime, payload: view, preview: view }),
+      },
+    });
+    if (confirmation) return confirmation;
     return runOrDiagnose(['classroom', 'submissions', 'return', pos(courseId), pos(courseworkId), pos(submissionId)], { account });
   });
 
@@ -354,16 +582,16 @@ export function registerClassroomTools(server: McpServer): void {
   });
 
   server.registerTool('gog_classroom_announcements_create', {
-    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,
+    description: 'Create an announcement in a Google Classroom course. Unless state is DRAFT with no scheduled time '
+      + '(which students cannot see; a scheduled draft publishes itself), 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 and no scheduled time.' + 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 (DRAFT is visible only to teachers and needs no confirmation)'),
-      scheduled: z.string().optional().describe('Scheduled publish time'),
+      state: z.enum(['PUBLISHED', 'DRAFT']).optional().describe('State (an unscheduled DRAFT is visible only to teachers and needs no confirmation)'),
+      scheduled: z.string().optional().describe('Scheduled publish time (asks the user to confirm, even for a DRAFT)'),
       account: accountParam,
       confirmToken: confirmTokenParam,
     }),
@@ -371,9 +599,10 @@ export function registerClassroomTools(server: McpServer): void {
     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') {
+    // An unscheduled draft reaches nobody until a teacher publishes it: it is
+    // this tool's own staging twin, so it needs no confirmation. A scheduled
+    // one publishes itself.
+    if (state !== 'DRAFT' || scheduled) {
       const read = await readCourse(courseId, account);
       if (read.error) return read.error;
       const publishes = scheduled ? `at ${scheduled}` : 'immediately';

package/src/tools/docs.ts

@@ -3,6 +3,12 @@ import { z } from 'zod';
 import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 import { pos } from '../argv.js';
 import type { GogArg } from '../runner.js';
+import { vetCommentsRun } from '../dispatch-confirmation.js';
+
+/** gog_docs_run must not post the comments gog_docs_comments_add / _reply would ask about. */
+export function vetDocsRun(subcommand: string, args: readonly string[]): string | undefined {
+  return vetCommentsRun('docs', subcommand, args);
+}
 
 export function registerDocsTools(server: McpServer): void {
   server.registerTool('gog_docs_info', {
@@ -106,5 +112,5 @@ export function registerDocsTools(server: McpServer): void {
     return runOrDiagnose(['docs', 'structure', pos(docId)], { account });
   });
 
-  registerRunTool(server, { service: 'docs', examples: '"copy", "clear", "insert", "sed", "export"' });
+  registerRunTool(server, { service: 'docs', examples: '"copy", "clear", "insert", "sed", "export"', vet: vetDocsRun });
 }

package/src/tools/drive.ts

@@ -8,13 +8,32 @@ 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';
+import { CONFIRM_FALLBACK_DESCRIPTION, confirmTokenParam, gatedElsewhere, hasTrueFlag, refusedInRun, requireDispatchConfirmation, vetCommentsRun, 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;
+// gog's spellings (internal/cmd/drive*.go; aliases per `gog schema` 0.41.0).
+const DRIVE_DELETE_WORDS = new Set(['delete', 'rm', 'del']);
+
+/** gog_drive_run must not do what gog_drive_share / comments / a permanent delete would ask about. */
+export function vetDriveRun(subcommand: string, args: readonly string[]): string | undefined {
+  const sub = subcommand.toLowerCase();
+  if (sub === 'share') return gatedElsewhere('gog drive share', 'gog_drive_run', 'grants access to a file', 'gog_drive_share');
+  if (DRIVE_DELETE_WORDS.has(sub) && hasTrueFlag(args, 'permanent')) {
+    return gatedElsewhere(`gog drive ${sub} --permanent`, 'gog_drive_run', 'deletes a file for good, bypassing the trash', 'gog_drive_delete');
+  }
+  // `bulk update-role --from=reader --to=writer` (and `bulk remove-public`)
+  // rewrites the permissions of every matching file under a folder, with no
+  // positional path for the path guard to see and no file for a preview to
+  // name (SEC-1, fleet-audit #930). `permissions` only lists.
+  if (sub === 'bulk') {
+    return gatedElsewhere('gog drive bulk', 'gog_drive_run',
+      'rewrites sharing permissions across every matching file in a tree', 'gog_drive_share (one file at a time)');
+  }
+  // `unshare` removes a collaborator's access; the dedicated tool shows the
+  // host a structured, annotated call rather than an opaque argv.
+  if (sub === 'unshare') {
+    return refusedInRun('gog drive unshare', 'gog_drive_run', "removes someone's access to a file", 'Use gog_drive_unshare.');
+  }
+  return vetCommentsRun('drive', sub, args);
 }
 
 // A native Google Doc exports to text directly; anything else (PDF, image,
@@ -36,6 +55,36 @@ export function shareTargetMeta(raw: string): { name?: string; mimeType?: string
   }
 }
 
+/**
+ * A Drive/Docs comment as a reply's prompt shows it: who wrote it, what it
+ * says and whether it is resolved. Unreadable output names nothing.
+ */
+export function commentSnapshot(raw: string): { author?: string; content?: string; resolved?: boolean } {
+  let comment: { content?: unknown; resolved?: unknown; author?: { displayName?: unknown; emailAddress?: unknown } } | undefined;
+  try {
+    const parsed = JSON.parse(raw) as ({ comment?: typeof comment } & NonNullable<typeof comment>) | null;
+    comment = parsed?.comment ?? parsed ?? undefined;
+  } catch {
+    comment = undefined;
+  }
+  const name = typeof comment?.author?.displayName === 'string' ? comment.author.displayName : undefined;
+  const email = typeof comment?.author?.emailAddress === 'string' ? comment.author.emailAddress : undefined;
+  const author = name && email ? `${name} <${email}>` : name ?? email;
+  return {
+    ...(author ? { author } : {}),
+    ...(typeof comment?.content === 'string' ? { content: comment.content } : {}),
+    ...(typeof comment?.resolved === 'boolean' ? { resolved: comment.resolved } : {}),
+  };
+}
+
+/**
+ * The people a comment's text +mentions (or @mentions) by email — Drive
+ * notifies each of them, so a comment's prompt names them.
+ */
+export function commentMentions(text: string): string[] {
+  return [...new Set(text.match(/(?<=[+@])[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g) ?? [])];
+}
+
 function fileMeta(raw: string): { name?: string; mimeType?: string; size?: number } {
   const parsed = JSON.parse(raw) as { file?: DriveMeta } & DriveMeta;
   const f = parsed.file ?? parsed;
@@ -171,16 +220,39 @@ export function registerDriveTools(server: McpServer): void {
   });
 
   server.registerTool('gog_drive_delete', {
-    description: 'Move a Google Drive file to trash, or permanently delete it with permanent=true (irreversible).',
+    description: 'Move a Google Drive file to trash, or permanently delete it with permanent=true (irreversible). A '
+      + 'permanent delete reads the file and asks the MCP host to show the user a confirmation prompt naming it first; '
+      + 'nothing is deleted unless they accept. Moving to trash is recoverable and does not ask.'
+      + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       fileId: z.string().describe('File ID to delete'),
-      permanent: z.boolean().optional().describe('Permanently delete instead of moving to trash (irreversible)'),
+      permanent: z.boolean().optional().describe('Permanently delete instead of moving to trash (irreversible; asks the user first)'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ fileId, permanent, account }) => {
+  }, async ({ fileId, permanent, account, confirmToken }, ctx) => {
     const args: GogArg[] = ['drive', 'delete', pos(fileId)];
-    if (permanent) args.push('--permanent');
+    if (permanent) {
+      const got = await runOrDiagnose(['drive', 'get', pos(fileId)], { account });
+      if (got.isError) return got;
+      const target = { file: { id: fileId, ...shareTargetMeta(resultText(got)) }, permanent: true };
+      const confirmation = await requireDispatchConfirmation(ctx, {
+        action: 'drive.delete-permanent',
+        message: 'Review and confirm PERMANENTLY deleting this file — it skips the trash and cannot be recovered:',
+        confirmationLabel: 'Confirm that this file should be permanently deleted now.',
+        details: target,
+        unsupportedNote: 'Move it to the trash instead (permanent=false); the user can empty the trash from Google Drive.',
+        fallback: {
+          tool: 'gog_drive_delete',
+          account,
+          confirmToken,
+          subject: () => ({ target: fileId, payload: target, preview: target }),
+        },
+      });
+      if (confirmation) return confirmation;
+      args.push('--permanent');
+    }
     // gog gates drive delete behind a confirmation; the runner injects
     // --no-input, so without --force it refuses at runtime.
     args.push('--force');

package/src/tools/gmail.ts

@@ -7,7 +7,7 @@ import { attachInlineParam, inlineAttachmentArgs } from '../attachments.js';
 import type { InlineAttachmentInput } from '../attachments.js';
 import { attachmentDetails, attachmentNames, attachmentPreview, bodyPreview, CONFIRM_FALLBACK_DESCRIPTION, confirmTokenParam, extractEmails, logGmailDispatch, replyDispatchOp, requireGmailDispatchConfirmation, resultText, senderPreview } from '../gmail-dispatch-guard.js';
 import { pos } from '../argv.js';
-import { hasCommandWord } from '../dispatch-confirmation.js';
+import { gatedElsewhere, hasCommandWord, hasTrueFlag } from '../dispatch-confirmation.js';
 import { confinePath, confinePaths } from '../file-roots.js';
 
 // gmail reply / reply-all share an identical flag set (gog 0.27+); they differ
@@ -264,6 +264,40 @@ async function sendReply(
 // `gog schema`, but they reach Google), so both spellings are refused.
 const GMAIL_RUN_BLOCKED_SETTINGS = new Set(['forwarding', 'autoforward', 'filters', 'delegates']);
 
+// Fleet audit 2026-09-24 SEC-6: a batch delete bypasses the Trash, a send-as
+// alias makes Google email the target and gives the account a new sending
+// identity, and an enabled vacation responder auto-replies to every sender.
+// Each has a dedicated tool that asks; gog accepts sendas and vacation both
+// under `settings` and one level up. Aliases per `gog schema` 0.41.0.
+const GMAIL_DELETE_WORDS = new Set(['delete', 'rm', 'del', 'remove']);
+const GMAIL_CREATE_WORDS = new Set(['create', 'add', 'new']);
+const GMAIL_UPDATE_WORDS = new Set(['update', 'edit', 'set']);
+const SENDAS = new Set(['sendas']);
+const VACATION = new Set(['vacation']);
+
+function vetGmailGatedRun(sub: string, args: readonly string[]): string | undefined {
+  if (sub === 'batch') {
+    const word = hasCommandWord(args, GMAIL_DELETE_WORDS);
+    return word
+      ? gatedElsewhere(`gog gmail batch ${word.toLowerCase()}`, 'gog_gmail_run', 'deletes mail for good, bypassing the Trash', 'gog_gmail_batch_delete')
+      : undefined;
+  }
+  if (sub !== 'settings' && sub !== 'sendas' && sub !== 'vacation') return undefined;
+  const words = sub === 'settings' ? args : [sub, ...args];
+  if (hasCommandWord(words, SENDAS)) {
+    const word = hasCommandWord(args, GMAIL_CREATE_WORDS);
+    if (word) {
+      return gatedElsewhere(`gog gmail sendas ${word.toLowerCase()}`, 'gog_gmail_run',
+        'makes Google email the address and adds a sending identity', 'gog_gmail_sendas_create');
+    }
+  }
+  if (hasCommandWord(words, VACATION) && hasCommandWord(args, GMAIL_UPDATE_WORDS) && hasTrueFlag(args, 'enable')) {
+    return gatedElsewhere('gog gmail vacation update --enable', 'gog_gmail_run',
+      'turns on an auto-reply to every sender', 'gog_gmail_vacation_update');
+  }
+  return undefined;
+}
+
 export function vetGmailRun(subcommand: string, args: readonly string[]): string | undefined {
   if (subcommand === 'autoreply') {
     return 'gog gmail autoreply sends mail and is not available through gog_gmail_run. Use gog_gmail_autoreply, which asks the user to confirm.';
@@ -271,6 +305,8 @@ export function vetGmailRun(subcommand: string, args: readonly string[]): string
   if (GMAIL_RUN_BLOCKED_SETTINGS.has(subcommand)) {
     return `gog gmail ${subcommand} can forward or hand over mail and is not available through gog_gmail_run. Use the dedicated gog_gmail_* tool instead.`;
   }
+  const gated = vetGmailGatedRun(subcommand.toLowerCase(), args);
+  if (gated) return gated;
   if (subcommand === 'settings') {
     // A global flag can take its value as the next token (`settings --color
     // never filters ...`), so the word is not necessarily args[0]. Refuse it

package/src/tools/sheets.ts

@@ -6,6 +6,21 @@ import { accountParam, runOrDiagnose, registerRunTool, diagnose } from './utils.
 import { expandAnchorRange, countNonEmptyCells } from './sheets-a1.js';
 import { pos } from '../argv.js';
 import type { GogArg } from '../runner.js';
+import { gatedElsewhere, hasCommandWord } from '../dispatch-confirmation.js';
+
+// Fleet audit 2026-09-24 SEC-6: each of these starts a BigQuery job billed to
+// --billing-project. Spellings per `gog schema` 0.41.0.
+const DATASOURCE_ALIASES = new Set(['datasource', 'data-source', 'data-sources', 'connected-sheets']);
+const DATASOURCE_BILLED = new Set(['add', 'update', 'refresh']);
+
+/** gog_sheets_run must not start the billed queries gog_sheets_datasource_* would ask about. */
+export function vetSheetsRun(subcommand: string, args: readonly string[]): string | undefined {
+  if (!DATASOURCE_ALIASES.has(subcommand.toLowerCase())) return undefined;
+  const word = hasCommandWord(args, DATASOURCE_BILLED)?.toLowerCase();
+  return word
+    ? gatedElsewhere(`gog sheets datasource ${word}`, 'gog_sheets_run', 'runs a billed BigQuery job', `gog_sheets_datasource_${word}`)
+    : undefined;
+}
 
 // Cell value type: matches what gog sheets --values-json accepts (passed
 // straight to the Sheets API as userEnteredValue). Strings starting with
@@ -144,5 +159,5 @@ export function registerSheetsTools(server: McpServer): void {
     return runOrDiagnose(['sheets', 'find-replace', pos(spreadsheetId), pos(find), pos(replace)], { account });
   });
 
-  registerRunTool(server, { service: 'sheets', examples: '"freeze", "add-tab", "rename-tab"' });
+  registerRunTool(server, { service: 'sheets', examples: '"freeze", "add-tab", "rename-tab"', vet: vetSheetsRun });
 }

package/src/tools/utils.ts

@@ -302,10 +302,11 @@ export function formatAccountList(raw: string): string {
 
 // Turn a thrown error into a diagnosed error result (`isError: true`): the
 // error text, an actionable hint when the failure class is recognised (auth /
-// transient / off-grid write), and the list of configured accounts. Callers
-// that need to surface a failure without going through runOrDiagnose (e.g. a
-// pre-write verification read that must abort) can reuse this so the error
-// keeps the same diagnostic quality as everywhere else.
+// transient / off-grid write), and — on an auth failure only — the list of
+// configured accounts. Callers that need to surface a failure without going
+// through runOrDiagnose (e.g. a pre-write verification read that must abort)
+// can reuse this so the error keeps the same diagnostic quality as everywhere
+// else.
 export async function diagnose(err: unknown): Promise<CallToolResult> {
   const errText = errorText(err);
 
@@ -333,6 +334,11 @@ export async function diagnose(err: unknown): Promise<CallToolResult> {
         : isGridLimitError
           ? GRID_LIMIT_HINT
           : '';
+  // The account list answers one question — WHICH account is signed in — so it
+  // is appended only when the failure is about that (PRIV-1, fleet-audit
+  // #1012). Every other error used to echo every identity on the host to the
+  // model, and spawn a `gog auth list`, for nothing.
+  if (!isAuthError && !isInvalidGrant) return errorResult(`${errText}${hint}`);
   try {
     const accounts = formatAccountList(await run(['auth', 'list']));
     return errorResult(`${errText}\n\nConfigured accounts:\n${accounts || '(none)'}${hint}`);