gogcli-mcp 4.2.4 → 4.3.0

package/src/tools/gmail.ts

@@ -5,7 +5,9 @@ import { finalizeGmailSearch, fetchGmailPages } from '../gmail-results.js';
 import type { GogArg } from '../runner.js';
 import { attachInlineParam, inlineAttachmentArgs } from '../attachments.js';
 import type { InlineAttachmentInput } from '../attachments.js';
-import { extractEmails, logGmailDispatch, replyDispatchOp, requireGmailDispatchConfirmation, resultText } from '../gmail-dispatch-guard.js';
+import { attachmentNames, bodyPreview, extractEmails, logGmailDispatch, replyDispatchOp, requireGmailDispatchConfirmation, resultText } from '../gmail-dispatch-guard.js';
+import { pos } from '../argv.js';
+import { confinePath, confinePaths } from '../file-roots.js';
 
 // gmail reply / reply-all share an identical flag set (gog 0.27+); they differ
 // only in the subcommand and default recipient set (reply → sender; reply-all
@@ -24,7 +26,7 @@ export const replySchema = {
   remove: z.array(z.string()).optional().describe('Remove these recipients from all fields (repeatable) — e.g. to drop someone from a reply-all.'),
   subject: z.string().optional().describe('Override reply subject (default: "Re: <original>"). A changed subject starts a NEW Gmail thread.'),
   noQuote: z.boolean().optional().describe('Do not include the original message quoted below the reply (default: the original is quoted)'),
-  attach: z.array(z.string()).optional().describe('File paths to attach (repeatable), resolved ON THE GOG SERVER\'s filesystem — NOT this client\'s. Only usable when gog runs on the same machine you do (local stdio); on a hosted deployment (e.g. mcp-host) these paths do not exist and the call fails with "no such file or directory" — use attachInline there. Read on the server, base64-encoded with a MIME type inferred from the extension.'),
+  attach: z.array(z.string()).optional().describe('File paths to attach (repeatable), resolved ON THE GOG SERVER\'s filesystem — NOT this client\'s. Only usable when gog runs on the same machine you do (local stdio); on a hosted deployment (e.g. mcp-host) these paths do not exist and the call fails with "no such file or directory" — use attachInline there. Read on the server, base64-encoded with a MIME type inferred from the extension. Must be inside the server\'s GOG_FILE_ROOTS directories (default ~/gogcli-mcp-files).'),
   attachInline: attachInlineParam,
   from: z.string().optional().describe('Send from this email address (must be a verified send-as alias)'),
   autoFromAddressedAlias: z.boolean().optional().describe('When from is omitted, send from the verified send-as alias the original message was addressed TO, instead of the account\'s primary address — so a reply to mail sent to an alias goes back out from that alias. Ignored when from is set.'),
@@ -53,8 +55,18 @@ export type ReplyFlags = {
   signatureFile?: string;
 };
 
+// Every server path a reply/draft names must sit inside GOG_FILE_ROOTS: each is
+// read on the gog host and mailed out, so unconfined it is a file-exfiltration
+// primitive (audit SEC-3). Checked before anything else touches gog.
+export function confineReplyPaths(f: Pick<ReplyFlags, 'attach' | 'bodyHtmlFile' | 'signatureFile'>): void {
+  confinePaths(f.attach, 'attach');
+  if (f.bodyHtmlFile) confinePath(f.bodyHtmlFile, 'bodyHtmlFile');
+  if (f.signatureFile) confinePath(f.signatureFile, 'signatureFile');
+}
+
 export function appendReplyFlags(args: GogArg[], f: ReplyFlags): void {
   assertNotBoth('bodyHtml', 'bodyHtmlFile', f.bodyHtml, f.bodyHtmlFile);
+  confineReplyPaths(f);
   if (f.body) args.push(payloadArg('body', 'body-file', f.body));
   if (f.bodyHtml) args.push(payloadArg('body-html', 'body-html-file', f.bodyHtml, 'html'));
   else if (f.bodyHtmlFile) args.push(`--body-html-file=${f.bodyHtmlFile}`);
@@ -150,7 +162,7 @@ async function sendReply(
   flags: ReplyFlags,
   ctx: ServerContext,
 ) {
-  const metaResult = await runOrDiagnose(['gmail', 'get', messageId, '--format=metadata'], { account });
+  const metaResult = await runOrDiagnose(['gmail', 'get', pos(messageId), '--format=metadata'], { account });
   if (metaResult.isError) return metaResult;
   const headers = parseMetadataHeaders(resultText(metaResult));
   const recipients = computeReplyRecipients(kind, headers, flags);
@@ -161,16 +173,51 @@ async function sendReply(
     subject: flags.subject || (headers.subject ? `Re: ${headers.subject}` : undefined),
     quoting: !flags.noQuote,
     bodyLength: (flags.body ?? flags.bodyHtml ?? '').length,
+    bodyPreview: bodyPreview(flags.body ?? flags.bodyHtml),
+    bodyHtmlFile: flags.bodyHtmlFile,
     attachmentCount: (flags.attach?.length ?? 0) + (flags.attachInline?.length ?? 0),
+    attachments: attachmentNames(flags.attach, flags.attachInline),
   });
   if (confirmation) return confirmation;
-  const args: GogArg[] = ['gmail', kind, messageId];
+  const args: GogArg[] = ['gmail', kind, pos(messageId)];
   appendReplyFlags(args, flags);
   const result = await runOrDiagnose(args, { account });
   if (!result.isError) logGmailDispatch(toolName, recipients, account);
   return result;
 }
 
+// What --gmail-no-send does NOT cover (verified on gog 0.41.0): a bulk
+// auto-reply, and the settings that route future mail to someone else —
+// forwarding addresses, auto-forwarding, filters (which can forward) and
+// delegates (which grant another account the mailbox). Each has a dedicated,
+// reviewable tool; none may ride the escape hatch.
+//
+// gog accepts these both under `settings` AND one level up, as
+// `gog gmail filters|forwarding|autoforward|delegates ...` (left out of
+// `gog schema`, but they reach Google), so both spellings are refused.
+const GMAIL_RUN_BLOCKED_SETTINGS = new Set(['forwarding', 'autoforward', 'filters', 'delegates']);
+
+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.';
+  }
+  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.`;
+  }
+  if (subcommand === 'settings') {
+    // kong lets flags precede the command word, and 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 wherever it appears; a
+    // legitimate settings call carrying one of these words as a value is rare
+    // and has a dedicated tool anyway.
+    const blocked = args.find((a) => GMAIL_RUN_BLOCKED_SETTINGS.has(a.toLowerCase()));
+    if (blocked) {
+      return `gog gmail settings ${blocked} can forward or hand over mail and is not available through gog_gmail_run. Use the dedicated gog_gmail_* tool instead.`;
+    }
+  }
+  return undefined;
+}
+
 export function registerGmailTools(server: McpServer): void {
   server.registerTool('gog_gmail_search', {
     description: 'Search Gmail threads using Gmail query syntax (e.g. "from:alice subject:invoice is:unread"). The query is passed verbatim to Gmail; a bare name token (from:alison) matches per Gmail\'s own heuristics, a full address (from:alison@example.com) is exact. To match a contact across several addresses, OR them: from:(a@x.com OR b@y.com). '
@@ -189,7 +236,7 @@ export function registerGmailTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ query, max, pageToken, page, maxPages, all, fromContact, account }) => {
-    const args = ['gmail', 'search', query];
+    const args: GogArg[] = ['gmail', 'search', pos(query)];
     if (max !== undefined) args.push(`--max=${max}`);
     if (all) args.push('--all');
     if (fromContact) args.push(`--from-contact=${fromContact}`);
@@ -226,7 +273,7 @@ export function registerGmailTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ messageId, format, sanitizeContent, account }) => {
-    const args = ['gmail', 'get', messageId];
+    const args: GogArg[] = ['gmail', 'get', pos(messageId)];
     if (format) args.push(`--format=${format}`);
     if (sanitizeContent) args.push('--sanitize-content');
     return runOrDiagnose(args, { account });
@@ -234,7 +281,7 @@ export function registerGmailTools(server: McpServer): void {
 
   server.registerTool('gog_gmail_send', {
     description:
-      'SENDS MAIL — asks the MCP host to show a confirmation prompt with the recipients, subject, and body size. '
+      'SENDS MAIL — asks the MCP host to show a confirmation prompt with the recipients, subject, a preview of the body and the attachment names. '
       + 'Mail is sent only after the user accepts that prompt. '
       + 'Two ways to attach a file: `attach` takes paths READ ON THE GOG SERVER, and '
       + '`attachInline` takes the bytes themselves. Use attachInline unless you know the file exists on '
@@ -255,11 +302,12 @@ export function registerGmailTools(server: McpServer): void {
       replyToMessageId: z.string().optional().describe('Message ID to thread this message against — sets In-Reply-To/References only. It does NOT quote the original (pass quote for that), inherit its recipients, or prefix the subject with "Re:". For an actual reply use gog_gmail_reply.'),
       threadId: z.string().optional().describe('Thread ID to thread this message within. Same caveat as replyToMessageId: threading only, no quote and no inherited subject or recipients.'),
       quote: z.boolean().optional().describe('Include the original message quoted below the body. Requires replyToMessageId or threadId. gog quotes by DEFAULT on gmail reply but never on gmail send, so without this a threaded send arrives with the original nowhere in it.'),
-      attach: z.array(z.string()).optional().describe('File paths to attach (repeatable), resolved ON THE GOG SERVER\'s filesystem — NOT this client\'s. Only usable when gog runs on the same machine you do (local stdio); on a hosted deployment (e.g. mcp-host) these paths do not exist and the call fails with "no such file or directory" — use attachInline there. Each file is read on the server, base64-encoded with a MIME type inferred from its extension, and added as a multipart attachment.'),
+      attach: z.array(z.string()).optional().describe('File paths to attach (repeatable), resolved ON THE GOG SERVER\'s filesystem — NOT this client\'s. Only usable when gog runs on the same machine you do (local stdio); on a hosted deployment (e.g. mcp-host) these paths do not exist and the call fails with "no such file or directory" — use attachInline there. Each file is read on the server, base64-encoded with a MIME type inferred from its extension, and added as a multipart attachment. Must be inside the server\'s GOG_FILE_ROOTS directories (default ~/gogcli-mcp-files).'),
       attachInline: attachInlineParam,
       account: accountParam,
     }),
   }, async ({ to, subject, body, cc, bcc, replyToMessageId, threadId, quote, attach, attachInline, account }, ctx) => {
+    confinePaths(attach, 'attach');
     // Built (and validated — inlineAttachmentArgs throws on bad base64 or an
     // oversize file) BEFORE the confirmation request, on both paths: a prompt that
     // skipped this would tell a caller "looks fine, send it" about an
@@ -289,9 +337,11 @@ export function registerGmailTools(server: McpServer): void {
     const confirmation = requireGmailDispatchConfirmation(ctx, 'gmail.send', {
       to, cc, bcc, recipients, recipientCount: recipients.length, subject,
       bodyLength: body.length,
+      bodyPreview: bodyPreview(body),
       threaded: Boolean(replyToMessageId || threadId),
       quoting: Boolean(quote),
       attachmentCount: (attach?.length ?? 0) + (attachInline?.length ?? 0),
+      attachments: attachmentNames(attach, attachInline),
     });
     if (confirmation) return confirmation;
     const result = await runOrDiagnose(args, { account });
@@ -317,7 +367,7 @@ export function registerGmailTools(server: McpServer): void {
   // ==========================================================================
   server.registerTool('gog_gmail_reply', {
     description:
-      'SENDS MAIL — asks the MCP host to show a confirmation prompt with the resolved recipient, subject, and body size. '
+      'SENDS MAIL — asks the MCP host to show a confirmation prompt with the resolved recipient, subject, a preview of the body and the attachment names. '
       + 'Mail is sent only after the user accepts that prompt. To STAGE a reply instead '
       + 'of sending it, use gog_gmail_drafts_reply (gogcli-mcp-gmail only), which never needs confirmation. '
       + 'Reply to a Gmail message (goes to the original sender only). USE THIS, not gog_gmail_send, whenever you are '
@@ -331,12 +381,13 @@ export function registerGmailTools(server: McpServer): void {
     inputSchema: sendReplySchema,
   }, async ({ messageId, account, ...flags }, ctx) => {
     assertNotBoth('bodyHtml', 'bodyHtmlFile', flags.bodyHtml, flags.bodyHtmlFile);
+    confineReplyPaths(flags);
     return sendReply('reply', 'gog_gmail_reply', messageId, account, flags, ctx);
   });
 
   server.registerTool('gog_gmail_reply_all', {
     description:
-      'SENDS MAIL — asks the MCP host to show a confirmation prompt with the resolved recipients, subject, and body size. '
+      'SENDS MAIL — asks the MCP host to show a confirmation prompt with the resolved recipients, subject, a preview of the body and the attachment names. '
       + 'Mail is sent only after the user accepts that prompt. To STAGE a '
       + 'reply-all instead of sending it, use gog_gmail_drafts_reply_all (gogcli-mcp-gmail only), which never needs '
       + 'confirmation. '
@@ -347,8 +398,17 @@ export function registerGmailTools(server: McpServer): void {
     inputSchema: sendReplySchema,
   }, async ({ messageId, account, ...flags }, ctx) => {
     assertNotBoth('bodyHtml', 'bodyHtmlFile', flags.bodyHtml, flags.bodyHtmlFile);
+    confineReplyPaths(flags);
     return sendReply('reply-all', 'gog_gmail_reply_all', messageId, account, flags, ctx);
   });
 
-  registerRunTool(server, { service: 'gmail', examples: '"archive", "mark-read", "labels"' });
+  registerRunTool(server, {
+    service: 'gmail',
+    examples: '"archive", "mark-read", "labels"',
+    // gog's --gmail-no-send blocks send/reply/forward/drafts send and all of
+    // their aliases at runtime (verified on gog 0.41.0). Sending goes through the
+    // confirmed tools, never this escape hatch.
+    gmailNoSend: true,
+    vet: vetGmailRun,
+  });
 }

package/src/tools/sheets.ts

@@ -4,6 +4,8 @@ import { run } from '../runner.js';
 import { rawTextResult } from '@chrischall/mcp-utils';
 import { accountParam, runOrDiagnose, registerRunTool, diagnose } from './utils.js';
 import { expandAnchorRange, countNonEmptyCells } from './sheets-a1.js';
+import { pos } from '../argv.js';
+import type { GogArg } from '../runner.js';
 
 // Cell value type: matches what gog sheets --values-json accepts (passed
 // straight to the Sheets API as userEnteredValue). Strings starting with
@@ -31,7 +33,7 @@ export function registerSheetsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ spreadsheetId, range, account }) => {
-    return runOrDiagnose(['sheets', 'get', spreadsheetId, range], { account });
+    return runOrDiagnose(['sheets', 'get', pos(spreadsheetId), pos(range)], { account });
   });
 
   server.registerTool('gog_sheets_update', {
@@ -52,7 +54,7 @@ export function registerSheetsTools(server: McpServer): void {
       const readRange = expandAnchorRange(range, values.length, cols);
       let existing: string;
       try {
-        existing = await run(['sheets', 'get', spreadsheetId, readRange], { account });
+        existing = await run(['sheets', 'get', pos(spreadsheetId), pos(readRange)], { account });
       } catch (err) {
         // Couldn't read the target — refuse to write rather than risk an
         // overwrite, and diagnose the read failure (auth/transient/etc.) the
@@ -70,7 +72,7 @@ export function registerSheetsTools(server: McpServer): void {
         );
       }
     }
-    const args = ['sheets', 'update', spreadsheetId, range, `--values-json=${JSON.stringify(values)}`];
+    const args: GogArg[] = ['sheets', 'update', pos(spreadsheetId), pos(range), `--values-json=${JSON.stringify(values)}`];
     if (dry_run) args.push('--dry-run');
     if (fail_on_formula_error) args.push('--fail-on-formula-error');
     return runOrDiagnose(args, { account });
@@ -87,7 +89,7 @@ export function registerSheetsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ spreadsheetId, range, values, account, dry_run }) => {
-    const args = ['sheets', 'append', spreadsheetId, range, `--values-json=${JSON.stringify(values)}`];
+    const args: GogArg[] = ['sheets', 'append', pos(spreadsheetId), pos(range), `--values-json=${JSON.stringify(values)}`];
     if (dry_run) args.push('--dry-run');
     return runOrDiagnose(args, { account });
   });
@@ -102,7 +104,7 @@ export function registerSheetsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ spreadsheetId, range, account, dry_run }) => {
-    const args = ['sheets', 'clear', spreadsheetId, range];
+    const args: GogArg[] = ['sheets', 'clear', pos(spreadsheetId), pos(range)];
     if (dry_run) args.push('--dry-run');
     return runOrDiagnose(args, { account });
   });
@@ -115,7 +117,7 @@ export function registerSheetsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ spreadsheetId, account }) => {
-    return runOrDiagnose(['sheets', 'metadata', spreadsheetId], { account });
+    return runOrDiagnose(['sheets', 'metadata', pos(spreadsheetId)], { account });
   });
 
   server.registerTool('gog_sheets_create', {
@@ -126,7 +128,7 @@ export function registerSheetsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ title, account }) => {
-    return runOrDiagnose(['sheets', 'create', title], { account });
+    return runOrDiagnose(['sheets', 'create', pos(title)], { account });
   });
 
   server.registerTool('gog_sheets_find_replace', {
@@ -139,7 +141,7 @@ export function registerSheetsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ spreadsheetId, find, replace, account }) => {
-    return runOrDiagnose(['sheets', 'find-replace', spreadsheetId, find, replace], { account });
+    return runOrDiagnose(['sheets', 'find-replace', pos(spreadsheetId), pos(find), pos(replace)], { account });
   });
 
   registerRunTool(server, { service: 'sheets', examples: '"freeze", "add-tab", "rename-tab"' });

package/src/tools/slides.ts

@@ -1,11 +1,15 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
+import { pos } from '../argv.js';
+import { confinePath } from '../file-roots.js';
+import type { GogArg } from '../runner.js';
 
 export function registerSlidesTools(server: McpServer): void {
   server.registerTool('gog_slides_export', {
-    description: 'Export a Google Slides presentation to a local file (pdf or pptx).',
-    annotations: { readOnlyHint: true },
+    description: 'Export a Google Slides presentation to a local file (pdf or pptx). The out path must be inside the server\'s GOG_FILE_ROOTS directories.',
+    // Writes a file on the gog host and can overwrite one: not read-only.
+    annotations: { readOnlyHint: false, destructiveHint: true },
     inputSchema: z.object({
       presentationId: z.string().describe('Presentation ID'),
       out: z.string().optional().describe('Output file path'),
@@ -14,7 +18,8 @@ export function registerSlidesTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ presentationId, out, format, overwrite, account }) => {
-    const args = ['slides', 'export', presentationId];
+    if (out) confinePath(out, 'out');
+    const args: GogArg[] = ['slides', 'export', pos(presentationId)];
     if (out) args.push(`--out=${out}`);
     if (format) args.push(`--format=${format}`);
     if (overwrite) args.push('--overwrite');
@@ -29,7 +34,7 @@ export function registerSlidesTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ presentationId, account }) => {
-    return runOrDiagnose(['slides', 'info', presentationId], { account });
+    return runOrDiagnose(['slides', 'info', pos(presentationId)], { account });
   });
 
   server.registerTool('gog_slides_create', {
@@ -42,7 +47,7 @@ export function registerSlidesTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ title, parent, template, account }) => {
-    const args = ['slides', 'create', title];
+    const args: GogArg[] = ['slides', 'create', pos(title)];
     if (parent) args.push(`--parent=${parent}`);
     if (template) args.push(`--template=${template}`);
     return runOrDiagnose(args, { account });
@@ -58,7 +63,7 @@ export function registerSlidesTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ presentationId, title, parent, account }) => {
-    const args = ['slides', 'copy', presentationId, title];
+    const args: GogArg[] = ['slides', 'copy', pos(presentationId), pos(title)];
     if (parent) args.push(`--parent=${parent}`);
     return runOrDiagnose(args, { account });
   });
@@ -71,7 +76,7 @@ export function registerSlidesTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ presentationId, account }) => {
-    return runOrDiagnose(['slides', 'list-slides', presentationId], { account });
+    return runOrDiagnose(['slides', 'list-slides', pos(presentationId)], { account });
   });
 
   server.registerTool('gog_slides_read_slide', {
@@ -84,10 +89,10 @@ export function registerSlidesTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ presentationId, slideId, detail, account }) => {
-    const args = ['slides', 'read-slide', presentationId, slideId];
+    const args: GogArg[] = ['slides', 'read-slide', pos(presentationId), pos(slideId)];
     if (detail) args.push('--detail');
     return runOrDiagnose(args, { account });
   });
 
-  registerRunTool(server, { service: 'slides', examples: '"add-slide", "delete-slide", "update-notes"' });
+  registerRunTool(server, { service: 'slides', examples: '"delete-slide", "update-notes"' });
 }

package/src/tools/tasks.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 registerTasksTools(server: McpServer): void {
   server.registerTool('gog_tasks_lists', {
@@ -21,7 +23,7 @@ export function registerTasksTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ tasklistId, account }) => {
-    return runOrDiagnose(['tasks', 'list', tasklistId], { account });
+    return runOrDiagnose(['tasks', 'list', pos(tasklistId)], { account });
   });
 
   server.registerTool('gog_tasks_get', {
@@ -33,7 +35,7 @@ export function registerTasksTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ tasklistId, taskId, account }) => {
-    return runOrDiagnose(['tasks', 'get', tasklistId, taskId], { account });
+    return runOrDiagnose(['tasks', 'get', pos(tasklistId), pos(taskId)], { account });
   });
 
   server.registerTool('gog_tasks_add', {
@@ -47,7 +49,7 @@ export function registerTasksTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ tasklistId, title, notes, due, account }) => {
-    const args = ['tasks', 'add', tasklistId, `--title=${title}`];
+    const args: GogArg[] = ['tasks', 'add', pos(tasklistId), `--title=${title}`];
     if (notes) args.push(`--notes=${notes}`);
     if (due) args.push(`--due=${due}`);
     return runOrDiagnose(args, { account });
@@ -62,7 +64,7 @@ export function registerTasksTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ tasklistId, taskId, account }) => {
-    return runOrDiagnose(['tasks', 'done', tasklistId, taskId], { account });
+    return runOrDiagnose(['tasks', 'done', pos(tasklistId), pos(taskId)], { account });
   });
 
   server.registerTool('gog_tasks_delete', {
@@ -76,7 +78,7 @@ export function registerTasksTools(server: McpServer): void {
   }, async ({ tasklistId, taskId, account }) => {
     // gog gates this delete behind a confirmation; the runner injects
     // --no-input, so without --force it refuses at runtime.
-    return runOrDiagnose(['tasks', 'delete', tasklistId, taskId, '--force'], { account });
+    return runOrDiagnose(['tasks', 'delete', pos(tasklistId), pos(taskId), '--force'], { account });
   });
 
   registerRunTool(server, { service: 'tasks', examples: '"update", "undo", "clear"' });

package/src/tools/utils.ts

@@ -5,6 +5,8 @@ import { run } from '../runner.js';
 import type { GogArg } from '../runner.js';
 import { normalizeTimestamps } from '../timestamps.js';
 import { stripConsumedPageToken } from '../pagination.js';
+import { assertSafeForwardedArgs, assertSafeSubcommand } from '../arg-guard.js';
+import { assertRunPathsConfined, positionalPathTool } from '../run-path-guard.js';
 
 // Byte size at or below which a payload stays on the plain inline flag.
 //
@@ -110,7 +112,7 @@ export const paginationParams = {
 // Append pagination flags to an argv array. Mirrors the shape of
 // paginationParams above. Use together to keep call sites concise.
 export function pushPaginationFlags(
-  args: string[],
+  args: GogArg[],
   p: { max?: number; pageToken?: string; page?: string; all?: boolean },
 ): void {
   if (p.max !== undefined) args.push(`--max=${p.max}`);
@@ -122,6 +124,14 @@ export function pushPaginationFlags(
 // Register a `gog_<service>_run` escape-hatch tool. 11 services currently
 // register an identical-shape tool; this factory keeps them in lockstep.
 // Pass `omitAccount: true` only for auth, which doesn't take --account.
+//
+// THE ARGS ARE MODEL-SUPPLIED AND FORWARDED VERBATIM, so every call is vetted
+// before gog sees it (audit SEC-1): a safety-control override
+// (`--readonly=false`, `--disable-commands=`, `--account=…`, a bare `--`, …) is
+// refused rather than forwarded, and the subcommand must be a plain word.
+// `allowedSubcommands` narrows a service to a named subset (auth: never
+// `tokens export`), `vet` lets a service refuse specific shapes, and
+// `gmailNoSend` pins gog's own `--gmail-no-send` on.
 export function registerRunTool(
   server: McpServer,
   options: {
@@ -130,11 +140,33 @@ export function registerRunTool(
     omitAccount?: boolean;
     /** Extra sentence appended to the description (used by auth to point to gog_auth_add). */
     note?: string;
+    /** When set, only these subcommands may run; everything else is refused. */
+    allowedSubcommands?: readonly string[];
+    /** Service-specific refusal: return a reason to refuse, or undefined to allow. */
+    vet?: (subcommand: string, args: readonly string[]) => string | undefined;
+    /** Inject gog's --gmail-no-send, so no send can be smuggled through this tool. */
+    gmailNoSend?: boolean;
   },
 ): void {
-  const { service, examples, omitAccount = false, note } = options;
+  const { service, examples, omitAccount = false, note, allowedSubcommands, vet, gmailNoSend = false } = options;
+  // The examples go straight into the schema the model reads, so every one must
+  // be a subcommand this tool actually runs. A stale example (#391: drive
+  // "upload" after #390 refused it) fails here, at registration, not in use.
+  for (const [, example] of examples.matchAll(/"([^"]+)"/g)) {
+    const refused = (allowedSubcommands && !allowedSubcommands.includes(example))
+      || vet?.(example, [])
+      || positionalPathTool(service, example);
+    if (refused) {
+      throw new Error(`gog_${service}_run example "${example}" is refused by the tool itself; list a subcommand it runs.`);
+    }
+  }
   const baseDescription = `Run any gog ${service} subcommand not covered by the other tools. Run \`gog ${service} --help\` for the full list of subcommands, or \`gog ${service} <subcommand> --help\` for flags on a specific subcommand.`;
-  const description = note ? `${baseDescription} ${note}` : baseDescription;
+  const restriction = allowedSubcommands
+    ? ` Only these subcommands are available: ${allowedSubcommands.join(', ')}.`
+    : '';
+  const safety = ' Flags that override server safety controls (--readonly, --enable-commands, --disable-commands, --account, --access-token, --home, --client, --gmail-no-send, --no-input) and a bare "--" are refused.'
+    + ' Local file paths (--out, --out-dir, --attach, --file, --*-file, @file JSON) must be inside GOG_FILE_ROOTS; subcommands that take a local path positionally (e.g. drive upload) are refused in favour of their dedicated tools.';
+  const description = `${baseDescription}${restriction}${safety}${note ? ` ${note}` : ''}`;
   const inputSchema: Record<string, z.ZodTypeAny> = {
     subcommand: z.string().describe(`The gog ${service} subcommand to run, e.g. ${examples}`),
     args: z.array(z.string()).describe('Additional positional args and flags'),
@@ -148,7 +180,21 @@ export function registerRunTool(
     inputSchema: z.object(inputSchema),
   }, async (rawArgs) => {
     const { subcommand, args, account } = rawArgs as { subcommand: string; args: string[]; account?: string };
-    return runOrDiagnose([service, subcommand, ...args], { account });
+    try {
+      assertSafeSubcommand(subcommand);
+      assertSafeForwardedArgs(args);
+      if (allowedSubcommands && !allowedSubcommands.includes(subcommand)) {
+        throw new Error(
+          `gog ${service} ${subcommand} is not available through gog_${service}_run. Allowed: ${allowedSubcommands.join(', ')}.`,
+        );
+      }
+      const refusal = vet?.(subcommand, args);
+      if (refusal) throw new Error(refusal);
+      assertRunPathsConfined(service, subcommand, args);
+    } catch (err) {
+      return errorResult(errorText(err));
+    }
+    return runOrDiagnose([service, subcommand, ...args], gmailNoSend ? { account, gmailNoSend } : { account });
   });
 }
 
@@ -359,7 +405,7 @@ function isRejectedFieldMask(err: unknown): boolean {
 
 async function runProjected(
   args: GogArg[],
-  options: { account?: string; lossless?: boolean; fieldsMask?: string },
+  options: { account?: string; lossless?: boolean; fieldsMask?: string; gmailNoSend?: boolean },
 ): Promise<string> {
   const { fieldsMask } = options;
   if (!fieldsMask) return run(args, options);
@@ -377,7 +423,7 @@ async function runProjected(
 
 export async function runOrDiagnose(
   args: GogArg[],
-  options: { account?: string; lossless?: boolean; fieldsMask?: string; stripMedia?: boolean },
+  options: { account?: string; lossless?: boolean; fieldsMask?: string; stripMedia?: boolean; gmailNoSend?: boolean },
 ): Promise<CallToolResult> {
   try {
     // The single seam every tool's output passes through. Normalizing here —

package/tests/arg-guard.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import { forbiddenArgReason, assertSafeForwardedArgs, assertSafeSubcommand } from '../src/arg-guard.js';
+
+describe('forbiddenArgReason', () => {
+  // Each of these would let a model-supplied arg override a control the
+  // operator (or this wrapper) set: gog takes the LAST value of a repeated flag,
+  // so `--readonly=false` after the injected `--readonly` turns writes back on.
+  it.each([
+    '--readonly',
+    '--readonly=false',
+    '--readonly=0',
+    '--enable-commands=gmail.send',
+    '--enable-commands-exact=gmail send',
+    '--disable-commands=',
+    '--disable-commands',
+    '--access-token=ya29.x',
+    '--home=/tmp/other',
+    '--account=attacker@example.com',
+    '--account',
+    '--acct=attacker@example.com',
+    '--client=other',
+    '--gmail-no-send=false',
+    '--no-input=false',
+    '--non-interactive=false',
+    '--noninteractive=false',
+    '--READONLY=false',
+    '--Account=attacker@example.com',
+    '-a',
+    '-aattacker@example.com',
+    '-ja',
+    '--',
+  ])('rejects %j', (arg) => {
+    expect(forbiddenArgReason(arg)).toMatch(/not allowed/);
+  });
+
+  it.each([
+    'msg1',
+    '--title=New',
+    '--max=5',
+    '-y',
+    '-5',
+    'has:attachment',
+    'a--readonly',
+    '',
+    // Legitimate command flags that merely share a leading word with a control
+    // (gog_zoom_auth_setup builds the first three). Matched as bare prefixes
+    // they were refused, so zoom auth setup could never run.
+    '--account-id=abc',
+    '--client-id=x',
+    '--client-secret=y',
+    '--home-dir=x',
+    '--readonly-note=x',
+  ])('allows %j', (arg) => {
+    expect(forbiddenArgReason(arg)).toBeUndefined();
+  });
+
+  it('names the separator specifically for a bare --', () => {
+    expect(forbiddenArgReason('--')).toMatch(/"--"/);
+  });
+});
+
+describe('assertSafeForwardedArgs', () => {
+  it('passes a clean list', () => {
+    expect(() => assertSafeForwardedArgs(['file1', '--parent=x'])).not.toThrow();
+  });
+
+  it('throws naming the first offending arg', () => {
+    expect(() => assertSafeForwardedArgs(['x', '--readonly=false'])).toThrow(/--readonly=false/);
+  });
+});
+
+describe('assertSafeSubcommand', () => {
+  it.each(['archive', 'mark-read', 'labels', 'add-tab'])('allows %j', (s) => {
+    expect(() => assertSafeSubcommand(s)).not.toThrow();
+  });
+
+  it.each(['--readonly=false', '-a', '', 'Send Now', '../x'])('rejects %j', (s) => {
+    expect(() => assertSafeSubcommand(s)).toThrow(/subcommand/);
+  });
+});