gogcli-mcp 4.2.5 → 4.4.0

package/src/tools/gmail.ts

@@ -5,7 +5,10 @@ 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 { 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 { 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 +27,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 +56,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}`);
@@ -86,8 +99,9 @@ export function appendReplyFlags(args: GogArg[], f: ReplyFlags): void {
 // The send-side reply/reply-all schema, distinct from the shared replySchema
 // above. gog_gmail_drafts_reply / _reply_all (gogcli-mcp-gmail) reuse
 // replySchema verbatim and must never gain a send-confirmation input — draft
-// tools stage mail, while send tools request confirmation through MCP.
-const sendReplySchema = z.object(replySchema);
+// tools stage mail, while send tools request confirmation (through MCP, or the
+// opt-in confirmToken fallback, which is why only THIS schema carries it).
+const sendReplySchema = z.object({ ...replySchema, confirmToken: confirmTokenParam });
 
 // gog's own `reply`/`reply-all` response never echoes the resolved
 // recipients when replying to a single message (the common case: gog only
@@ -136,6 +150,62 @@ export function computeReplyRecipients(
   return emails;
 }
 
+/** `message.threadId` out of `gog gmail get --format=metadata --json`, if present. */
+export function metadataThreadId(raw: string): string | undefined {
+  try {
+    const threadId = (JSON.parse(raw) as { message?: { threadId?: unknown } } | null)?.message?.threadId;
+    return typeof threadId === 'string' ? threadId : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// The token fallback's preview and bound payload for a reply. To/Cc/Bcc are the
+// same approximation computeReplyRecipients makes (gog composes the final list),
+// split by field so the user can see who is on Bcc.
+function replyTokenSubject(
+  kind: 'reply' | 'reply-all',
+  messageId: string,
+  account: string | undefined,
+  headers: Record<string, string>,
+  threadId: string | undefined,
+  flags: ReplyFlags,
+) {
+  const removed = new Set(extractEmails(...(flags.remove ?? [])));
+  const keep = (emails: string[]) => emails.filter((e) => !removed.has(e));
+  const to = keep(extractEmails(headers.from, ...(kind === 'reply-all' ? [headers.to] : []), ...(flags.to ?? [])));
+  const cc = keep(extractEmails(...(kind === 'reply-all' ? [headers.cc] : []), ...(flags.cc ?? [])));
+  const bcc = keep(extractEmails(...(flags.bcc ?? [])));
+  const attachments = attachmentDetails(flags.attach, flags.attachInline);
+  const subject = flags.subject || (headers.subject ? `Re: ${headers.subject}` : undefined);
+  const from = flags.from ?? (flags.autoFromAddressedAlias ? 'the send-as alias the original was addressed to' : senderPreview(account));
+  const localFiles = attachmentDetails([flags.bodyHtmlFile, flags.signatureFile].filter((p): p is string => Boolean(p)), undefined);
+  return {
+    target: messageId,
+    payload: {
+      kind, to, cc, bcc, subject, from,
+      body: flags.body, bodyHtml: flags.bodyHtml, localFiles,
+      signature: Boolean(flags.signature), signatureFrom: flags.signatureFrom,
+      attachments, quote: !flags.noQuote,
+      threadId, inReplyTo: headers.message_id, references: headers.references,
+    },
+    preview: {
+      from, to, cc, bcc, subject,
+      body: flags.body,
+      ...(flags.bodyHtml ? { bodyHtml: flags.bodyHtml } : {}),
+      ...(flags.bodyHtmlFile ? { bodyHtmlFile: flags.bodyHtmlFile } : {}),
+      ...(flags.signature || flags.signatureFrom || flags.signatureFile
+        ? { signature: flags.signatureFile ?? flags.signatureFrom ?? 'the Gmail signature of the sending address' }
+        : {}),
+      quotesOriginal: !flags.noQuote,
+      attachments: attachmentPreview(attachments),
+      replyingToMessageId: messageId,
+      threadId,
+      inReplyTo: headers.message_id,
+    },
+  };
+}
+
 // Shared by gog_gmail_reply and gog_gmail_reply_all: fetch the target
 // message's headers (always — the prompt needs them and so does the audit
 // log on the accepted path), then confirm and send.
@@ -149,28 +219,71 @@ async function sendReply(
   account: string | undefined,
   flags: ReplyFlags,
   ctx: ServerContext,
+  confirmToken?: string,
 ) {
-  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 metaText = resultText(metaResult);
+  const headers = parseMetadataHeaders(metaText);
   const recipients = computeReplyRecipients(kind, headers, flags);
-  const confirmation = requireGmailDispatchConfirmation(ctx, replyDispatchOp(kind), {
+  const confirmation = await requireGmailDispatchConfirmation(ctx, replyDispatchOp(kind), {
     messageId,
     recipients,
     recipientCount: recipients.length,
     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),
+  }, {
+    tool: toolName,
+    account,
+    confirmToken,
+    // The metadata read above IS the phase-2 re-read: it runs on every call,
+    // so the original's Message-ID/References are fresh here.
+    subject: () => replyTokenSubject(kind, messageId, account, headers, metadataThreadId(metaText), flags),
   });
   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') {
+    // 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 = hasCommandWord(args, GMAIL_RUN_BLOCKED_SETTINGS);
+    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 +302,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 +339,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 +347,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 '
@@ -244,7 +357,8 @@ export function registerGmailTools(server: McpServer): void {
       + 'and byte sizes — check it to confirm the files were embedded. '
       + 'NOT the tool for answering a message: replyToMessageId only files this in the right thread — the '
       + 'subject, recipients and body are entirely yours, and the original is not quoted unless you set '
-      + 'quote. Use gog_gmail_reply / gog_gmail_reply_all instead, which inherit all three.',
+      + 'quote. Use gog_gmail_reply / gog_gmail_reply_all instead, which inherit all three.'
+      + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       to: z.string().describe('Recipient(s), comma-separated'),
@@ -255,11 +369,13 @@ 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,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ to, subject, body, cc, bcc, replyToMessageId, threadId, quote, attach, attachInline, account }, ctx) => {
+  }, async ({ to, subject, body, cc, bcc, replyToMessageId, threadId, quote, attach, attachInline, account, confirmToken }, 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
@@ -286,12 +402,35 @@ export function registerGmailTools(server: McpServer): void {
     args.push(...inline);
 
     const recipients = extractEmails(to, cc, bcc);
-    const confirmation = requireGmailDispatchConfirmation(ctx, 'gmail.send', {
+    const confirmation = await 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),
+    }, {
+      tool: 'gog_gmail_send',
+      account,
+      confirmToken,
+      // Nothing is stored between the phases: the payload IS the arguments,
+      // so phase 2 must repeat them and any difference is a changed send.
+      subject: () => {
+        const attachments = attachmentDetails(attach, attachInline);
+        const from = senderPreview(account);
+        return {
+          target: replyToMessageId ?? threadId ?? '',
+          payload: { from, to, cc, bcc, subject, body, attachments, threadId, inReplyTo: replyToMessageId, quote: Boolean(quote) },
+          preview: {
+            from, to, cc, bcc, subject, body,
+            attachments: attachmentPreview(attachments),
+            threadId,
+            inReplyTo: replyToMessageId,
+            quotesOriginal: Boolean(quote),
+          },
+        };
+      },
     });
     if (confirmation) return confirmation;
     const result = await runOrDiagnose(args, { account });
@@ -317,7 +456,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 '
@@ -326,29 +465,41 @@ export function registerGmailTools(server: McpServer): void {
       + 'brand-new message, with the original nowhere in it. To answer every participant use gog_gmail_reply_all. '
       + 'The gogcli-mcp-gmail package adds two more routes with the same composition: gog_gmail_autoreply to reply '
       + 'across every message matching a query, and gog_gmail_drafts_reply to stage this exact reply as a draft '
-      + 'instead of sending it.',
+      + 'instead of sending it.'
+      + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: sendReplySchema,
-  }, async ({ messageId, account, ...flags }, ctx) => {
+  }, async ({ messageId, account, confirmToken, ...flags }, ctx) => {
     assertNotBoth('bodyHtml', 'bodyHtmlFile', flags.bodyHtml, flags.bodyHtmlFile);
-    return sendReply('reply', 'gog_gmail_reply', messageId, account, flags, ctx);
+    confineReplyPaths(flags);
+    return sendReply('reply', 'gog_gmail_reply', messageId, account, flags, ctx, confirmToken);
   });
 
   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. '
       + 'Reply to all participants of a Gmail message (the sender plus every To/Cc recipient). Same inherited "Re:" '
       + 'subject and quoted original as gog_gmail_reply. Use the remove flag to drop specific recipients from the '
-      + 'reply-all.',
+      + 'reply-all.'
+      + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: sendReplySchema,
-  }, async ({ messageId, account, ...flags }, ctx) => {
+  }, async ({ messageId, account, confirmToken, ...flags }, ctx) => {
     assertNotBoth('bodyHtml', 'bodyHtmlFile', flags.bodyHtml, flags.bodyHtmlFile);
-    return sendReply('reply-all', 'gog_gmail_reply_all', messageId, account, flags, ctx);
+    confineReplyPaths(flags);
+    return sendReply('reply-all', 'gog_gmail_reply_all', messageId, account, flags, ctx, confirmToken);
   });
 
-  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"' });