gogcli-mcp 4.2.5 → 4.4.0

package/src/tools/classroom.ts

@@ -1,6 +1,59 @@
 import { McpServer } from '@modelcontextprotocol/server';
 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', {
@@ -17,7 +70,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ state, teacher, student, max, pageToken, page, all, account }) => {
-    const args = ['classroom', 'courses', 'list'];
+    const args: GogArg[] = ['classroom', 'courses', 'list'];
     if (state) args.push(`--state=${state}`);
     if (teacher) args.push(`--teacher=${teacher}`);
     if (student) args.push(`--student=${student}`);
@@ -36,7 +89,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, account }) => {
-    return runOrDiagnose(['classroom', 'courses', 'get', courseId], { account });
+    return runOrDiagnose(['classroom', 'courses', 'get', pos(courseId)], { account });
   });
 
   server.registerTool('gog_classroom_students_list', {
@@ -51,7 +104,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, max, pageToken, page, all, account }) => {
-    const args = ['classroom', 'students', 'list', courseId];
+    const args: GogArg[] = ['classroom', 'students', 'list', pos(courseId)];
     if (max !== undefined) args.push(`--max=${max}`);
     const token = resolvePageToken({ pageToken, page });
     if (token) args.push(`--page=${token}`);
@@ -68,7 +121,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, userId, account }) => {
-    return runOrDiagnose(['classroom', 'students', 'get', courseId, userId], { account });
+    return runOrDiagnose(['classroom', 'students', 'get', pos(courseId), pos(userId)], { account });
   });
 
   server.registerTool('gog_classroom_teachers_list', {
@@ -83,7 +136,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, max, pageToken, page, all, account }) => {
-    const args = ['classroom', 'teachers', 'list', courseId];
+    const args: GogArg[] = ['classroom', 'teachers', 'list', pos(courseId)];
     if (max !== undefined) args.push(`--max=${max}`);
     const token = resolvePageToken({ pageToken, page });
     if (token) args.push(`--page=${token}`);
@@ -100,7 +153,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, userId, account }) => {
-    return runOrDiagnose(['classroom', 'teachers', 'get', courseId, userId], { account });
+    return runOrDiagnose(['classroom', 'teachers', 'get', pos(courseId), pos(userId)], { account });
   });
 
   server.registerTool('gog_classroom_roster', {
@@ -117,7 +170,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, students, teachers, max, pageToken, page, all, account }) => {
-    const args = ['classroom', 'roster', courseId];
+    const args: GogArg[] = ['classroom', 'roster', pos(courseId)];
     if (students) args.push('--students');
     if (teachers) args.push('--teachers');
     if (max !== undefined) args.push(`--max=${max}`);
@@ -143,7 +196,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, state, topic, orderBy, max, pageToken, page, all, scanPages, account }) => {
-    const args = ['classroom', 'coursework', 'list', courseId];
+    const args: GogArg[] = ['classroom', 'coursework', 'list', pos(courseId)];
     if (state) args.push(`--state=${state}`);
     if (topic) args.push(`--topic=${topic}`);
     if (orderBy) args.push(`--order-by=${orderBy}`);
@@ -164,7 +217,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, courseworkId, account }) => {
-    return runOrDiagnose(['classroom', 'coursework', 'get', courseId, courseworkId], { account });
+    return runOrDiagnose(['classroom', 'coursework', 'get', pos(courseId), pos(courseworkId)], { account });
   });
 
   server.registerTool('gog_classroom_submissions_list', {
@@ -183,7 +236,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, courseworkId, state, late, user, max, pageToken, page, all, account }) => {
-    const args = ['classroom', 'submissions', 'list', courseId, courseworkId];
+    const args: GogArg[] = ['classroom', 'submissions', 'list', pos(courseId), pos(courseworkId)];
     if (state) args.push(`--state=${state}`);
     if (late) args.push(`--late=${late}`);
     if (user) args.push(`--user=${user}`);
@@ -204,7 +257,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, courseworkId, submissionId, account }) => {
-    return runOrDiagnose(['classroom', 'submissions', 'get', courseId, courseworkId, submissionId], { account });
+    return runOrDiagnose(['classroom', 'submissions', 'get', pos(courseId), pos(courseworkId), pos(submissionId)], { account });
   });
 
   server.registerTool('gog_classroom_submissions_grade', {
@@ -219,7 +272,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, courseworkId, submissionId, draft, assigned, account }) => {
-    const args = ['classroom', 'submissions', 'grade', courseId, courseworkId, submissionId];
+    const args: GogArg[] = ['classroom', 'submissions', 'grade', pos(courseId), pos(courseworkId), pos(submissionId)];
     if (draft) args.push(`--draft=${draft}`);
     if (assigned) args.push(`--assigned=${assigned}`);
     return runOrDiagnose(args, { account });
@@ -235,7 +288,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, courseworkId, submissionId, account }) => {
-    return runOrDiagnose(['classroom', 'submissions', 'return', courseId, courseworkId, submissionId], { account });
+    return runOrDiagnose(['classroom', 'submissions', 'return', pos(courseId), pos(courseworkId), pos(submissionId)], { account });
   });
 
   server.registerTool('gog_classroom_submissions_turn_in', {
@@ -248,7 +301,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, courseworkId, submissionId, account }) => {
-    return runOrDiagnose(['classroom', 'submissions', 'turn-in', courseId, courseworkId, submissionId], { account });
+    return runOrDiagnose(['classroom', 'submissions', 'turn-in', pos(courseId), pos(courseworkId), pos(submissionId)], { account });
   });
 
   server.registerTool('gog_classroom_submissions_reclaim', {
@@ -261,7 +314,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, courseworkId, submissionId, account }) => {
-    return runOrDiagnose(['classroom', 'submissions', 'reclaim', courseId, courseworkId, submissionId], { account });
+    return runOrDiagnose(['classroom', 'submissions', 'reclaim', pos(courseId), pos(courseworkId), pos(submissionId)], { account });
   });
 
   server.registerTool('gog_classroom_announcements_list', {
@@ -278,7 +331,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, state, orderBy, max, pageToken, page, all, account }) => {
-    const args = ['classroom', 'announcements', 'list', courseId];
+    const args: GogArg[] = ['classroom', 'announcements', 'list', pos(courseId)];
     if (state) args.push(`--state=${state}`);
     if (orderBy) args.push(`--order-by=${orderBy}`);
     if (max !== undefined) args.push(`--max=${max}`);
@@ -297,23 +350,51 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, announcementId, account }) => {
-    return runOrDiagnose(['classroom', 'announcements', 'get', courseId, announcementId], { account });
+    return runOrDiagnose(['classroom', 'announcements', 'get', pos(courseId), pos(announcementId)], { account });
   });
 
   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 }) => {
-    const args = ['classroom', 'announcements', 'create', courseId, `--text=${text}`];
+  }, 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 });
   });
 
@@ -329,7 +410,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, max, pageToken, page, all, account }) => {
-    const args = ['classroom', 'topics', 'list', courseId];
+    const args: GogArg[] = ['classroom', 'topics', 'list', pos(courseId)];
     if (max !== undefined) args.push(`--max=${max}`);
     const token = resolvePageToken({ pageToken, page });
     if (token) args.push(`--page=${token}`);
@@ -346,7 +427,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, topicId, account }) => {
-    return runOrDiagnose(['classroom', 'topics', 'get', courseId, topicId], { account });
+    return runOrDiagnose(['classroom', 'topics', 'get', pos(courseId), pos(topicId)], { account });
   });
 
   server.registerTool('gog_classroom_invitations_list', {
@@ -362,7 +443,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ course, user, max, pageToken, page, all, account }) => {
-    const args = ['classroom', 'invitations', 'list'];
+    const args: GogArg[] = ['classroom', 'invitations', 'list'];
     if (course) args.push(`--course=${course}`);
     if (user) args.push(`--user=${user}`);
     if (max !== undefined) args.push(`--max=${max}`);
@@ -380,7 +461,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ invitationId, account }) => {
-    return runOrDiagnose(['classroom', 'invitations', 'get', invitationId], { account });
+    return runOrDiagnose(['classroom', 'invitations', 'get', pos(invitationId)], { account });
   });
 
   server.registerTool('gog_classroom_invitations_accept', {
@@ -391,7 +472,7 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ invitationId, account }) => {
-    return runOrDiagnose(['classroom', 'invitations', 'accept', invitationId], { account });
+    return runOrDiagnose(['classroom', 'invitations', 'accept', pos(invitationId)], { account });
   });
 
   server.registerTool('gog_classroom_profile_get', {
@@ -402,14 +483,15 @@ export function registerClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ userId, account }) => {
-    const args = ['classroom', 'profile', 'get'];
-    if (userId) args.push(userId);
+    const args: GogArg[] = ['classroom', 'profile', 'get'];
+    if (userId) args.push(pos(userId));
     return runOrDiagnose(args, { account });
   });
 
   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/contacts.ts

@@ -1,6 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
+import { pos } from '../argv.js';
+import type { GogArg } from '../runner.js';
 
 export function registerContactsTools(server: McpServer): void {
   server.registerTool('gog_contacts_search', {
@@ -11,7 +13,7 @@ export function registerContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ query, account }) => {
-    return runOrDiagnose(['contacts', 'search', query], { account });
+    return runOrDiagnose(['contacts', 'search', pos(query)], { account });
   });
 
   server.registerTool('gog_contacts_list', {
@@ -32,7 +34,7 @@ export function registerContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ resourceName, account }) => {
-    return runOrDiagnose(['contacts', 'get', resourceName], { account });
+    return runOrDiagnose(['contacts', 'get', pos(resourceName)], { account });
   });
 
   server.registerTool('gog_contacts_create', {
@@ -48,7 +50,7 @@ export function registerContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ givenName, familyName, email, phone, org, title, account }) => {
-    const args = ['contacts', 'create', `--given=${givenName}`];
+    const args: GogArg[] = ['contacts', 'create', `--given=${givenName}`];
     if (familyName) args.push(`--family=${familyName}`);
     if (email) args.push(`--email=${email}`);
     if (phone) args.push(`--phone=${phone}`);

package/src/tools/docs.ts

@@ -1,6 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
+import { pos } from '../argv.js';
+import type { GogArg } from '../runner.js';
 
 export function registerDocsTools(server: McpServer): void {
   server.registerTool('gog_docs_info', {
@@ -11,7 +13,7 @@ export function registerDocsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ docId, account }) => {
-    return runOrDiagnose(['docs', 'info', docId], { account });
+    return runOrDiagnose(['docs', 'info', pos(docId)], { account });
   });
 
   server.registerTool('gog_docs_cat', {
@@ -23,7 +25,7 @@ export function registerDocsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ docId, chips, account }) => {
-    const args = ['docs', 'cat', docId];
+    const args: GogArg[] = ['docs', 'cat', pos(docId)];
     if (chips) args.push('--chips');
     return runOrDiagnose(args, { account });
   });
@@ -36,7 +38,7 @@ export function registerDocsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ title, account }) => {
-    return runOrDiagnose(['docs', 'create', title], { account });
+    return runOrDiagnose(['docs', 'create', pos(title)], { account });
   });
 
   server.registerTool('gog_docs_write', {
@@ -62,7 +64,7 @@ export function registerDocsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ docId, text, append, checkOrphans, bullets, bulletPreset, ordered, noBullets, indentStart, indentEnd, indentFirstLine, spaceAbove, spaceBelow, keepLinesTogether, keepWithNext, batch, account }) => {
-    const args = ['docs', 'write', docId, `--text=${text}`];
+    const args: GogArg[] = ['docs', 'write', pos(docId), `--text=${text}`];
     if (append) args.push('--append');
     if (checkOrphans) args.push('--check-orphans');
     if (bullets) args.push('--bullets');
@@ -90,7 +92,7 @@ export function registerDocsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ docId, find, replace, account }) => {
-    return runOrDiagnose(['docs', 'find-replace', docId, find, replace], { account });
+    return runOrDiagnose(['docs', 'find-replace', pos(docId), pos(find), pos(replace)], { account });
   });
 
   server.registerTool('gog_docs_structure', {
@@ -101,7 +103,7 @@ export function registerDocsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ docId, account }) => {
-    return runOrDiagnose(['docs', 'structure', docId], { account });
+    return runOrDiagnose(['docs', 'structure', pos(docId)], { account });
   });
 
   registerRunTool(server, { service: 'docs', examples: '"copy", "clear", "insert", "sed", "export"' });

package/src/tools/drive.ts

@@ -1,10 +1,21 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import type { CallToolResult } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { rawTextResult, viewParam, resolveView } from '@chrischall/mcp-utils';
+import { errorResult, rawTextResult, viewParam, resolveView } from '@chrischall/mcp-utils';
+import { MAX_INLINE_ATTACHMENT_BYTES } from '../attachments.js';
 
 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
@@ -13,12 +24,31 @@ const GOOGLE_DOC_MIME = 'application/vnd.google-apps.document';
 
 // Parse `gog drive get` JSON into { name, mimeType }. gog nests the payload
 // under `file`; fall back to the top level if that ever changes.
-function fileMeta(raw: string): { name?: string; mimeType?: string } {
-  const parsed = JSON.parse(raw) as { file?: { name?: string; mimeType?: string }; name?: string; mimeType?: string };
+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;
-  return { name: f.name, mimeType: f.mimeType };
+  // Drive reports int64 fields as strings; native Google formats carry none.
+  const size = f.size === undefined ? undefined : Number(f.size);
+  return { name: f.name, mimeType: f.mimeType, size: Number.isFinite(size) ? size : undefined };
 }
 
+// The most gog_drive_read_bytes returns inline — the same 8 MiB per-file cap
+// the attachment path enforces. The bytes travel base64-encoded (4/3 larger)
+// inside one JSON-RPC message, and past this no MCP client accepts the result.
+export const MAX_DRIVE_READ_BYTES = MAX_INLINE_ATTACHMENT_BYTES;
+
 
 // The `compact` rung for gog_drive_ls, as a Google Drive field mask.
 //
@@ -52,7 +82,7 @@ export function registerDriveTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ folderId, max, pageToken, page, query, allDrives, view, account }) => {
-    const args = ['drive', 'ls'];
+    const args: GogArg[] = ['drive', 'ls'];
     if (folderId) args.push(`--parent=${folderId}`);
     if (max !== undefined) args.push(`--max=${max}`);
     const token = resolvePageToken({ pageToken, page });
@@ -78,7 +108,7 @@ export function registerDriveTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ query, view, account }) => {
-    return runOrDiagnose(['drive', 'search', query], {
+    return runOrDiagnose(['drive', 'search', pos(query)], {
       account,
       stripMedia: resolveView(view, ['compact', 'full']) === 'compact',
     });
@@ -99,7 +129,7 @@ export function registerDriveTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ fileId, view, account }) => {
-    return runOrDiagnose(['drive', 'get', fileId], {
+    return runOrDiagnose(['drive', 'get', pos(fileId)], {
       account,
       stripMedia: resolveView(view, ['compact', 'full']) === 'compact',
     });
@@ -113,7 +143,7 @@ export function registerDriveTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ name, account }) => {
-    return runOrDiagnose(['drive', 'mkdir', name], { account });
+    return runOrDiagnose(['drive', 'mkdir', pos(name)], { account });
   });
 
   server.registerTool('gog_drive_rename', {
@@ -125,7 +155,7 @@ export function registerDriveTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ fileId, newName, account }) => {
-    return runOrDiagnose(['drive', 'rename', fileId, newName], { account });
+    return runOrDiagnose(['drive', 'rename', pos(fileId), pos(newName)], { account });
   });
 
   server.registerTool('gog_drive_move', {
@@ -137,7 +167,7 @@ export function registerDriveTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ fileId, parentId, account }) => {
-    return runOrDiagnose(['drive', 'move', fileId, `--parent=${parentId}`], { account });
+    return runOrDiagnose(['drive', 'move', pos(fileId), `--parent=${parentId}`], { account });
   });
 
   server.registerTool('gog_drive_delete', {
@@ -149,7 +179,7 @@ export function registerDriveTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ fileId, permanent, account }) => {
-    const args = ['drive', 'delete', fileId];
+    const args: GogArg[] = ['drive', 'delete', pos(fileId)];
     if (permanent) args.push('--permanent');
     // gog gates drive delete behind a confirmation; the runner injects
     // --no-input, so without --force it refuses at runtime.
@@ -158,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'),
@@ -167,9 +200,40 @@ 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 }) => {
-    const args = ['drive', 'share', fileId, `--to=${to}`];
+  }, 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}`);
     if (role) args.push(`--role=${role}`);
@@ -201,7 +265,7 @@ export function registerDriveTools(server: McpServer): void {
   }, async ({ fileId, ocrLanguage, offset = 0, maxChars, account }) => {
     let tempDocId: string | undefined;
     try {
-      const { name, mimeType } = fileMeta(await run(['drive', 'get', fileId], { account }));
+      const { name, mimeType } = fileMeta(await run(['drive', 'get', pos(fileId)], { account }));
 
       // Native Docs export straight to text; everything else is OCR-converted first.
       let sourceId = fileId;
@@ -242,7 +306,7 @@ export function registerDriveTools(server: McpServer): void {
     } finally {
       // Always remove the temp Doc — on success, and on a mid-extraction failure.
       if (tempDocId) {
-        await run(['drive', 'delete', tempDocId, '--permanent', '--force'], { account }).catch(() => {});
+        await run(['drive', 'delete', pos(tempDocId), '--permanent', '--force'], { account }).catch(() => {});
       }
     }
   });
@@ -251,7 +315,7 @@ export function registerDriveTools(server: McpServer): void {
     description:
       'Fetch a Drive file\'s raw bytes and return them base64-encoded as an embedded resource — the ' +
       'generic fallback for callers that want the file itself (to parse locally) rather than extracted ' +
-      'text. For readable text from a PDF, prefer gog_drive_extract_text.',
+      'text. Files over 8 MiB are refused (checked before downloading). For readable text from a PDF, prefer gog_drive_extract_text.',
     annotations: { readOnlyHint: true },
     inputSchema: z.object({
       fileId: z.string().describe('Drive file ID'),
@@ -259,9 +323,21 @@ export function registerDriveTools(server: McpServer): void {
     }),
   }, async ({ fileId, account }): Promise<CallToolResult> => {
     try {
-      const { name, mimeType } = fileMeta(await run(['drive', 'get', fileId], { account }));
+      const { name, mimeType, size } = fileMeta(await run(['drive', 'get', pos(fileId)], { account }));
+      // Refuse an oversized file BEFORE fetching it (audit BUG-2): buffering a
+      // multi-GB file plus its base64 copy can take down the whole server.
+      if (size !== undefined && size > MAX_DRIVE_READ_BYTES) {
+        return errorResult(
+          `${name ?? fileId} is ${size} bytes, over the 8 MiB this tool returns inline. `
+          + 'Use gog_drive_extract_text for its text, or share its webViewLink (gog_drive_get) instead.',
+        );
+      }
       const params = JSON.stringify({ fileId, alt: 'media' });
-      const blob = await runBinary(['api', 'call', 'drive', 'v3', 'files.get', `--params=${params}`], { account });
+      // The cap also bounds the fetch itself, for files Drive reports no size for.
+      const blob = await runBinary(
+        ['api', 'call', 'drive', 'v3', 'files.get', `--params=${params}`],
+        { account, maxOutputBytes: MAX_DRIVE_READ_BYTES },
+      );
       const type = mimeType ?? 'application/octet-stream';
       // Several hosts (claude.ai among them) render embedded IMAGE resources
       // and reject every other type outright — "Resources of type
@@ -290,5 +366,5 @@ export function registerDriveTools(server: McpServer): void {
     }
   });
 
-  registerRunTool(server, { service: 'drive', examples: '"copy", "upload", "download", "permissions"' });
+  registerRunTool(server, { service: 'drive', examples: '"copy", "download", "permissions"', vet: vetDriveRun });
 }