gogcli-mcp 4.2.5 → 4.4.0

package/src/gmail-dispatch-guard.ts

@@ -1,10 +1,27 @@
 import type { CallToolResult, InputRequiredResult, ServerContext } from '@modelcontextprotocol/server';
-import { readEnvVar, requireConfirmation } from '@chrischall/mcp-utils';
+import { readEnvVar } from '@chrischall/mcp-utils';
+import { CONFIRM_SEND_INSTRUCTION, requireDispatchConfirmation, type DispatchTokenFallback } from './dispatch-confirmation.js';
+
+// The generic pieces moved to dispatch-confirmation.ts when Chat, Calendar,
+// Drive and Classroom joined the rail; re-exported so Gmail callers keep one import.
+export {
+  attachmentDetails,
+  attachmentNames,
+  BODY_PREVIEW_MAX,
+  bodyPreview,
+  attachmentPreview,
+  CONFIRM_FALLBACK_DESCRIPTION,
+  CONFIRM_SEND_INSTRUCTION as CONFIRM_INSTRUCTION,
+  confirmTokenParam,
+  resultText,
+  senderPreview,
+} from './dispatch-confirmation.js';
+export type { AttachmentDetail, DispatchTokenFallback, TokenSubject } from './dispatch-confirmation.js';
 
 // ============================================================================
-// THE SAFETY RAIL. gog_gmail_reply / reply_all / send / forward / autoreply are
-// the only tools in this fleet that put a message irreversibly into someone
-// else's mailbox on the FIRST call. Every other Gmail write either stages
+// THE SAFETY RAIL. gog_gmail_reply / reply_all / send / forward / autoreply /
+// drafts_send, and a filter that forwards, are the tools in this fleet that put
+// a message irreversibly into someone else's mailbox. Every other Gmail write either stages
 // something (drafts) or acts on mail already in this account (labels,
 // archive, trash). A caller that meant "save a draft" and picked the wrong
 // tool — or an agent that inherited the wrong reply target — used to find out
@@ -15,6 +32,12 @@ import { readEnvVar, requireConfirmation } from '@chrischall/mcp-utils';
 // user's accepted confirmation dispatches. The confirmation is never a tool
 // argument, so a model cannot bypass the user by setting a boolean itself.
 //
+// The one exception is OPT-IN: with GOG_SEND_CONFIRM_FALLBACK=token, a client
+// that cannot be prompted gets a two-phase preview + confirmToken instead of a
+// refusal (`DispatchTokenFallback`, send-confirm-token.ts). There the approval
+// IS a tool argument; see that file for exactly what the token does and does
+// not guarantee.
+//
 // A CLIENT THAT CANNOT SHOW THAT PROMPT gets a sentence rather than a prompt
 // it will refuse to deliver (`unsupportedNote`, mcp-utils `requireConfirmation`).
 // Measured on the mcp-host fleet 2026-09-20: claude.ai declares no MCP
@@ -26,7 +49,7 @@ import { readEnvVar, requireConfirmation } from '@chrischall/mcp-utils';
 // ============================================================================
 
 /**
- * The five dispatches this rail guards, spelled once.
+ * The dispatches this rail guards, spelled once.
  *
  * A UNION rather than `string`, because the staging-twin table below is keyed
  * by these values and a key that matches no call site is silent: it costs the
@@ -41,7 +64,14 @@ export type GmailDispatchOp =
   | 'gmail.reply'
   | 'gmail.reply-all'
   | 'gmail.forward'
-  | 'gmail.autoreply';
+  | 'gmail.autoreply'
+  // Sending a staged draft dispatches mail just as irreversibly as a direct
+  // send; draft-create then drafts-send was an unconfirmed two-step around the
+  // rail (audit SEC-2).
+  | 'gmail.drafts-send'
+  // A filter with a forward action sends every FUTURE matching message to
+  // another address — persistent exfiltration, not a one-off send.
+  | 'gmail.filter-forward';
 
 /** Every op, for tests that must cover the set rather than a chosen member. */
 export const GMAIL_DISPATCH_OPS: readonly GmailDispatchOp[] = [
@@ -50,6 +80,8 @@ export const GMAIL_DISPATCH_OPS: readonly GmailDispatchOp[] = [
   'gmail.reply-all',
   'gmail.forward',
   'gmail.autoreply',
+  'gmail.drafts-send',
+  'gmail.filter-forward',
 ];
 
 /**
@@ -66,9 +98,9 @@ export function replyDispatchOp(kind: 'reply' | 'reply-all'): GmailDispatchOp {
 
 /**
  * The staging twin of each dispatch, named in the refusal above. Every one of
- * these saves without sending, and `gog_gmail_drafts_send` then dispatches it —
- * which is the rail's own sanctioned two-step (staging is visible and
- * inspectable, so the send is never the FIRST call), not a way around it.
+ * these saves without sending. `gog_gmail_drafts_send` asks for confirmation
+ * too, so on a client that cannot show a prompt the way through is the USER
+ * sending the saved draft from Gmail — a human in the loop either way.
  *
  * `Partial<Record<…>>` and not an index signature: a key outside the union is
  * now rejected by the compiler, which is the whole point, while `autoreply`
@@ -83,24 +115,41 @@ const STAGING_TWIN: Partial<Record<GmailDispatchOp, string>> = {
   'gmail.send': 'gog_gmail_drafts_create',
 };
 
-/** Apply the shared stateless confirmation flow with Gmail-specific copy. */
-export function requireGmailDispatchConfirmation(
+// What to say when there is no staging twin but there IS still a way through.
+const UNSUPPORTED_NOTE: Partial<Record<GmailDispatchOp, string>> = {
+  'gmail.drafts-send': 'The draft is still saved: ask the user to review it and send it from Gmail.',
+};
+
+/**
+ * Apply the shared stateless confirmation flow with Gmail-specific copy.
+ *
+ * Elicitation stays the primary path and is untouched. Only when the caller
+ * declares it cannot be prompted AND a `fallback` is supplied AND
+ * GOG_SEND_CONFIRM_FALLBACK=token does the two-phase token flow run instead of
+ * the refusal; with the env unset, the refusal names that switch.
+ */
+export async function requireGmailDispatchConfirmation(
   ctx: ServerContext,
   op: GmailDispatchOp,
   details: Record<string, unknown>,
-): InputRequiredResult | CallToolResult | undefined {
+  fallback?: DispatchTokenFallback,
+): Promise<InputRequiredResult | CallToolResult | undefined> {
   const twin = STAGING_TWIN[op];
-  return requireConfirmation(ctx, {
+  const note = twin
+    ? `Stage it with ${twin} instead; the user can review the draft and send it from Gmail `
+      + '(gog_gmail_drafts_send also asks for confirmation).'
+    : UNSUPPORTED_NOTE[op];
+  return requireDispatchConfirmation(ctx, {
     action: op,
-    message: 'Review and confirm this email dispatch:',
+    message: op === 'gmail.filter-forward'
+      ? 'Review and confirm this mail-forwarding filter:'
+      : 'Review and confirm this email dispatch:',
     details,
-    confirmationLabel: 'Confirm that this email should be sent now.',
-    ...(twin
-      ? {
-          unsupportedNote: `Stage it with ${twin} instead, review the draft, `
-            + 'and send it with gog_gmail_drafts_send.',
-        }
-      : {}),
+    confirmationLabel: op === 'gmail.filter-forward'
+      ? 'Confirm that matching mail should be forwarded automatically from now on.'
+      : 'Confirm that this email should be sent now.',
+    unsupportedNote: note,
+    ...(fallback ? { fallback: { instruction: CONFIRM_SEND_INSTRUCTION, ...fallback } } : {}),
   });
 }
 
@@ -170,12 +219,3 @@ export function logGmailDispatch(tool: string, recipients: string[], account?: s
   };
   process.stderr.write(`${JSON.stringify(event)}\n`);
 }
-
-// The single place a CallToolResult's text is pulled back out, for the tools
-// here that need to read gog's own JSON before deciding what to preview or
-// log. Mirrors the shape every runOrDiagnose result actually returns
-// (content[0].text); never throws on an unexpected shape.
-export function resultText(result: CallToolResult): string {
-  const first = result.content[0];
-  return first && first.type === 'text' && typeof first.text === 'string' ? first.text : '{}';
-}

package/src/gmail-results.ts

@@ -3,6 +3,7 @@ import { rawTextResult } from '@chrischall/mcp-utils';
 import { run } from './runner.js';
 import { annotateTruncation, hasMorePages } from './pagination.js';
 import type { MatchCount } from './pagination.js';
+import { pos } from './argv.js';
 
 // Post-processing for Gmail search output, on the seam between gog's JSON and
 // the model client. Two guarantees live here, both of which exist because a
@@ -102,7 +103,7 @@ async function countMatches(
       maxResults: COUNT_PROBE_PAGE_SIZE,
       fields: `${itemsKey}/id,nextPageToken`,
     });
-    const raw = await run(['api', 'call', 'gmail', 'v1', method, `--params=${params}`], { account });
+    const raw = await run(['api', 'call', 'gmail', 'v1', pos(method), `--params=${params}`], { account });
     const parsed = JSON.parse(raw) as Record<string, unknown>;
     const items = parsed[itemsKey];
     if (!Array.isArray(items)) return {};
@@ -208,8 +209,13 @@ export async function fetchGmailPages(
     // Nothing collected yet means the caller should just see that result; once
     // pages ARE collected, return them WITH the cursor that was about to be
     // consumed, so the set still reads as truncated rather than complete.
+    // The failing page's own text rides along as `pageError` (audit QUAL-1):
+    // without it the caller sees only "more exist", retries the same failing
+    // page, and never learns WHY — e.g. that the account needs re-auth.
     if (parsed === undefined) {
-      return base === undefined ? result : finish(base, itemsKey, merged, token);
+      return base === undefined
+        ? result
+        : finish(base, itemsKey, merged, token, pageErrorText(result, itemsKey, pages + 1));
     }
     base = parsed;
     merged.push(...(parsed[itemsKey] as unknown[]));
@@ -253,14 +259,27 @@ function parsePage(
   return Array.isArray(obj[itemsKey]) ? obj : undefined;
 }
 
+// What went wrong on page `n` of a walk, bounded so a stray HTML page cannot
+// become the payload. An error result is already diagnosed text (hints and
+// all); anything else is output this walk could not read as a list.
+const PAGE_ERROR_MAX = 2000;
+function pageErrorText(result: CallToolResult, itemsKey: string, n: number): string {
+  const first = result.content[0];
+  const text = first?.type === 'text' ? first.text.slice(0, PAGE_ERROR_MAX) : '';
+  if (result.isError) return `page ${n} failed${text ? `: ${text}` : ''}`;
+  return `page ${n} returned output that is not a ${itemsKey} list`;
+}
+
 function finish(
   base: Record<string, unknown>,
   itemsKey: string,
   merged: unknown[],
   token: string | undefined,
+  pageError?: string,
 ): CallToolResult {
   const out: Record<string, unknown> = { ...base, [itemsKey]: merged };
   if (token === undefined) delete out.nextPageToken;
   else out.nextPageToken = token;
+  if (pageError !== undefined) out.pageError = pageError;
   return rawTextResult(JSON.stringify(out));
 }

package/src/lib.ts

@@ -26,11 +26,22 @@ export type { ReplyFlags } from './tools/gmail.js';
 // gmail sub-package's send-side forward/autoreply tools reuse these directly
 // rather than re-declaring the gate; the draft-side twins never import them.
 export {
+  attachmentDetails,
+  attachmentNames,
+  attachmentPreview,
+  bodyPreview,
+  CONFIRM_FALLBACK_DESCRIPTION,
+  confirmTokenParam,
   extractEmails,
   logGmailDispatch,
   requireGmailDispatchConfirmation,
   resultText,
+  senderPreview,
 } from './gmail-dispatch-guard.js';
+// The service-neutral rail for every other tool that reaches another person.
+export { requireDispatchConfirmation } from './dispatch-confirmation.js';
+export { readCourse } from './tools/classroom.js';
+export type { AttachmentDetail, DispatchTokenFallback, TokenSubject } from './gmail-dispatch-guard.js';
 export { run, runBinary, isGogFileArg, MIN_GOG_VERSION } from './runner.js';
 // Sub-package tools that read gog JSON through bare `run()` (rather than the
 // `runOrDiagnose` seam) must still apply this, or their timestamps skip the
@@ -45,6 +56,10 @@ export type { FinalizeOptions, GmailListMethod } from './gmail-results.js';
 export { bootstrapGogAuth, AUTH_BOOTSTRAP_MARKER } from './bootstrap-auth.js';
 export type { AuthBootstrapStatus, AuthBootstrapOptions } from './bootstrap-auth.js';
 export type { RunOptions, Spawner, GogArg, GogFileArg } from './runner.js';
+export { pos } from './argv.js';
+export { confinePath, confinePaths, confineAtFile, fileRoots, defaultFileRoot, FILE_ROOTS_ENV } from './file-roots.js';
+export { prepareDownloadRoot, removeDownload, ATTACHMENT_TTL_MS } from './attachment-root.js';
+export type { GogPositional } from './argv.js';
 // Caller-supplied attachment bytes — the only outbound attachment path that
 // works when the caller and gog share no filesystem (a hosted deployment such
 // as mcp-host). See src/attachments.ts.

package/src/run-path-guard.ts

@@ -0,0 +1,118 @@
+// GOG_FILE_ROOTS for the escape hatches (audit SEC-3/SEC-4).
+//
+// The structured tools confine every server-side path they accept, but a
+// `gog_<service>_run` forwards a model-supplied string[] verbatim, and gog reads
+// and writes local files through it just as readily: `drive upload
+// <gog's credentials.json>`, `gmail drafts create --attach=~/.ssh/id_rsa`,
+// `docs export --out=~/.zshrc`. Left open, that is the read-and-exfiltrate and
+// write-anywhere primitive the roots exist to close, and GOG_FILE_ROOTS would
+// only look like a boundary. So, before an escape hatch runs:
+//
+// - subcommands whose local path is a POSITIONAL are refused outright. Which
+//   positional is the path depends on the command, and kong lets flags sit
+//   anywhere, so it cannot be picked out reliably; each has a dedicated tool
+//   that confines it.
+// - every path-bearing FLAG value (`--out`, `--attach`, `--file`, `--*-file`,
+//   `--out-dir`, `--dir`, an `@file` JSON input, ...) must resolve inside the
+//   roots, whether it is attached (`--out=x`) or the next token (`--out x`).
+// - the short spellings `-o` / `-f` are refused, since a cluster (`-yf x`,
+//   `-o/etc/x`) hides the value; the long form is confined instead.
+// - flags that make gog RUN a local program (`--on-change`, `--on-new`,
+//   `--mmdc`) are refused: a model-chosen shell command is a strictly worse
+//   primitive than a path.
+//
+// Kept out of runner.ts for the same reason as arg-guard.ts: tool tests
+// automock the runner, and this has to run for real in the tool handlers.
+
+import { confinePath } from './file-roots.js';
+
+/** Escape-hatch subcommands whose local path is positional, and the tool to use instead. */
+const POSITIONAL_PATH_SUBCOMMANDS: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  appscript: { pull: 'gog_appscript_pull' },
+  drive: { upload: 'gog_drive_upload', sync: 'gog_drive_sync_push' },
+  gmail: { import: 'gog_gmail_import' },
+  slides: {
+    'add-slide': 'gog_slides_add_slide',
+    'insert-image': 'gog_slides_insert_image',
+    'replace-slide': 'gog_slides_replace_slide',
+  },
+};
+
+/** Long flags (lower-case, no dashes) whose value is a local path (from `gog schema`, v0.41.0). */
+const PATH_FLAGS = new Set(['out', 'output', 'out-dir', 'output-dir', 'dir', 'worker-dir', 'attach', 'file', 'key', 'cert', 'replacements']);
+
+/** Per service: flags that look like paths but carry Drive file IDs. */
+const ID_FLAGS: Readonly<Record<string, ReadonlySet<string>>> = {
+  drive: new Set(['file', 'filter-file']),
+};
+
+/** Flags whose value gog executes as a local command or program. */
+const EXEC_FLAGS = new Set(['on-change', 'on-new', 'mmdc']);
+
+// Single-dash clusters containing -o (--out) or -f (--file).
+const SHORT_PATH_CLUSTER = /^-(?!-)[A-Za-z]*[of]/;
+
+const LONG_FLAG = /^--([A-Za-z0-9][A-Za-z0-9-]*)(?:=([\s\S]*))?$/;
+
+function isPathFlag(service: string, name: string): boolean {
+  if (ID_FLAGS[service]?.has(name)) return false;
+  return PATH_FLAGS.has(name) || name.endsWith('-file');
+}
+
+function confineFlagValue(flag: string, value: string): void {
+  // `-` is stdin/stdout, which never names a file on the host.
+  if (value === '-') return;
+  confinePath(value, flag);
+  // kong splits a repeatable ([]string) flag on commas, so `--attach=a,b` is
+  // two paths: each must be inside the roots too.
+  for (const part of value.split(',')) {
+    if (part !== '' && part !== '-') confinePath(part, flag);
+  }
+}
+
+/** The dedicated tool to use when `gog <service> <subcommand>` is refused for a positional path, else undefined. */
+export function positionalPathTool(service: string, subcommand: string): string | undefined {
+  return POSITIONAL_PATH_SUBCOMMANDS[service]?.[subcommand];
+}
+
+/**
+ * Throw unless every local path in an escape-hatch call (`gog <service>
+ * <subcommand> ...args`) lies inside GOG_FILE_ROOTS (or the private attachment
+ * download root), and nothing in it would run a local program.
+ */
+export function assertRunPathsConfined(service: string, subcommand: string, args: readonly string[]): void {
+  const dedicated = positionalPathTool(service, subcommand);
+  if (dedicated) {
+    throw new Error(
+      `gog ${service} ${subcommand} reads or writes a local path given as a positional argument, so it is not available through gog_${service}_run. Use ${dedicated}, which confines the path to GOG_FILE_ROOTS.`,
+    );
+  }
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (SHORT_PATH_CLUSTER.test(arg)) {
+      throw new Error(
+        `The flag ${arg} is not allowed here: spell a path flag out as --out or --file (e.g. --out=<path>) so its path can be checked against GOG_FILE_ROOTS.`,
+      );
+    }
+    const match = LONG_FLAG.exec(arg);
+    if (!match) continue;
+    const name = match[1].toLowerCase();
+    if (EXEC_FLAGS.has(name)) {
+      throw new Error(`The flag --${name} is not allowed here: it runs a local program chosen by the caller.`);
+    }
+    const isJson = name.endsWith('-json');
+    if (!isJson && !isPathFlag(service, name)) continue;
+    let value = match[2];
+    if (value === undefined) {
+      value = args[i + 1];
+      if (value === undefined) continue;
+      i++;
+    }
+    if (isJson) {
+      // Inline JSON passes; `@path` reads a file, `@-` reads stdin.
+      if (value.startsWith('@')) confineFlagValue(`--${name}`, value.slice(1));
+      continue;
+    }
+    confineFlagValue(`--${name}`, value);
+  }
+}

package/src/runner.ts

@@ -2,6 +2,10 @@ import type { ChildProcess } from 'node:child_process';
 import { delimiter, join } from 'node:path';
 import { currentCallSignal, killOnCancel, parseBoolEnv, readEnvVar, redactSecrets as redactSharedSecrets } from '@chrischall/mcp-utils';
 import { naiveSourceTimeZone } from './timestamps.js';
+import { forbiddenArgReason } from './arg-guard.js';
+import { isGogPositional, type GogPositional } from './argv.js';
+
+export type { GogPositional } from './argv.js';
 
 export type Spawner = (
   command: string,
@@ -55,10 +59,10 @@ export interface GogFileArg {
   positional?: boolean;
 }
 
-export type GogArg = string | GogFileArg;
+export type GogArg = string | GogFileArg | GogPositional;
 
 export function isGogFileArg(arg: GogArg): arg is GogFileArg {
-  return typeof arg !== 'string';
+  return typeof arg !== 'string' && arg.kind === 'file';
 }
 
 export interface RunOptions {
@@ -97,6 +101,15 @@ export interface RunOptions {
   // (see OPAQUE_FIELD_VALUE) — so a field carrying real prose, which is where a
   // real leaked token would live, still gets redacted normally.
   opaqueFields?: readonly string[];
+  // Inject gog's global --gmail-no-send, which blocks every Gmail send
+  // (send, reply, forward, drafts send, users.messages.send via api call) at
+  // runtime. Set by the escape hatches so none of them can dispatch mail
+  // around the confirmation rail.
+  gmailNoSend?: boolean;
+  // Ceiling on the bytes gog may write to stdout. Past it the child is killed
+  // and the call rejects, so one oversized download (a multi-GB Drive file read
+  // through runBinary) cannot exhaust this process's memory.
+  maxOutputBytes?: number;
 }
 
 const TIMEOUT_MS = 30_000;
@@ -300,8 +313,8 @@ function formatTimeout(ms: number): string {
 // plain argv, and remove the temp dir afterwards — on success, on a non-zero
 // exit, and on timeout alike. A leaked temp file holds user email content.
 async function spawnWithTempFiles(
-  args: GogArg[],
-  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean },
+  args: Array<string | GogFileArg>,
+  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean; maxOutputBytes?: number },
 ): Promise<string> {
   const { mkdtemp, mkdir, writeFile, rm } = await import('node:fs/promises');
   const { tmpdir } = await import('node:os');
@@ -350,8 +363,8 @@ async function spawnWithTempFiles(
 // to happen synchronously within the `run()` call, which the fake-timer tests
 // in tests/runner.test.ts depend on.
 function spawnExecutor(
-  args: GogArg[],
-  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean },
+  args: Array<string | GogFileArg>,
+  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean; maxOutputBytes?: number },
 ): Promise<string> {
   if (args.some(isGogFileArg)) {
     return spawnWithTempFiles(args, opts);
@@ -365,9 +378,9 @@ function spawnExecutor(
 // injected `spawner` bypasses the real child_process spawn.
 async function spawnGog(
   fullArgs: string[],
-  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean },
+  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean; maxOutputBytes?: number },
 ): Promise<string> {
-  const { timeout, interactive = false, spawner, binary = false } = opts;
+  const { timeout, interactive = false, spawner, binary = false, maxOutputBytes } = opts;
   const spawn = spawner ?? (await import('node:child_process')).spawn as unknown as Spawner;
   const effectiveTimeout = timeout ?? TIMEOUT_MS;
 
@@ -404,7 +417,19 @@ async function spawnGog(
       reject(new Error(`gog timed out after ${formatTimeout(effectiveTimeout)}`));
     }, effectiveTimeout);
 
-    child.stdout!.on('data', (chunk: Buffer) => { stdoutChunks.push(chunk); });
+    let stdoutBytes = 0;
+    child.stdout!.on('data', (chunk: Buffer) => {
+      if (settled) return;
+      stdoutBytes += chunk.length;
+      if (maxOutputBytes !== undefined && stdoutBytes > maxOutputBytes) {
+        settled = true;
+        stopWatching();
+        child.kill();
+        reject(new Error(`gog output exceeded the limit: more than ${maxOutputBytes} bytes`));
+        return;
+      }
+      stdoutChunks.push(chunk);
+    });
     child.stderr!.on('data', (chunk: Buffer) => { stderrChunks.push(chunk); });
 
     child.on('close', (code: number | null) => {
@@ -458,12 +483,51 @@ async function spawnGog(
 // Assemble the full gog argv: the always-injected flags (--json/--color=never,
 // --no-input unless interactive, --readonly when opted in), --account, then the
 // caller's args. Shared by run() and runBinary() so both get identical flags.
+// Split the caller's argv into flag position and positional position.
+// pos()-marked values, positional file args, and anything after an explicit
+// `--` are positionals; they go after ONE `--` at the very end, in their
+// original order, so a value that starts with '-' is data, never a flag
+// (audit BUG-1). Commands and flags keep their relative order. With nothing
+// positional the argv is returned unchanged — no `--` at all.
+function placePositionals(args: GogArg[]): { flags: Array<string | GogFileArg>; positionals: Array<string | GogFileArg> } {
+  const flags: Array<string | GogFileArg> = [];
+  const positionals: Array<string | GogFileArg> = [];
+  let afterSeparator = false;
+  for (const arg of args) {
+    if (arg === '--') {
+      afterSeparator = true;
+    } else if (isGogPositional(arg)) {
+      positionals.push(arg.value);
+    } else if (afterSeparator || (isGogFileArg(arg) && arg.positional)) {
+      positionals.push(arg);
+    } else {
+      flags.push(arg);
+    }
+  }
+  return { flags, positionals };
+}
+
+// Refuse a safety-control override sitting in FLAG position. The tool layer
+// already vets model-supplied escape-hatch args (arg-guard.ts); this is the
+// backstop for every other path, so no tool can hand gog a `--readonly=false`
+// that would override the `--readonly` injected below (gog takes the LAST
+// value of a repeated flag). Positionals are exempt: after `--` they are data.
+function assertNoSafetyOverrides(flags: Array<string | GogFileArg>): void {
+  for (const arg of flags) {
+    if (typeof arg !== 'string') continue;
+    const reason = forbiddenArgReason(arg);
+    if (reason) throw new Error(reason);
+  }
+}
+
 function assembleArgs(
   args: GogArg[],
-  opts: { account?: string; interactive: boolean; readonly: boolean },
-): GogArg[] {
+  opts: { account?: string; interactive: boolean; readonly: boolean; gmailNoSend: boolean },
+): Array<string | GogFileArg> {
+  const { flags, positionals } = placePositionals(args);
+  assertNoSafetyOverrides(flags);
   const effectiveAccount = opts.account ?? readEnvVar('GOG_ACCOUNT');
-  const fullArgs: GogArg[] = ['--json', '--color=never'];
+  const fullArgs: Array<string | GogFileArg> = ['--json', '--color=never'];
   if (!opts.interactive) {
     fullArgs.push('--no-input');
   }
@@ -473,15 +537,19 @@ function assembleArgs(
   if (opts.readonly || readonlyEnvEnabled()) {
     fullArgs.push('--readonly');
   }
+  if (opts.gmailNoSend) {
+    fullArgs.push('--gmail-no-send');
+  }
   if (effectiveAccount) {
     fullArgs.push('--account', effectiveAccount);
   }
-  fullArgs.push(...args);
+  fullArgs.push(...flags);
+  if (positionals.length > 0) fullArgs.push('--', ...positionals);
   return fullArgs;
 }
 
 export async function run(args: GogArg[], options: RunOptions = {}): Promise<string> {
-  const { account, spawner, interactive = false, timeout, readonly = false, redactMode = 'full', opaqueFields } = options;
+  const { account, spawner, interactive = false, timeout, readonly = false, redactMode = 'full', opaqueFields, gmailNoSend = false } = options;
   const base = redactMode === 'tokens' ? redactGoogleTokens : redactSecrets;
   // Only OUTPUT carries opaque payloads. An error message is prose by
   // definition, so it always takes the plain redactor — exempting a field there
@@ -490,7 +558,7 @@ export async function run(args: GogArg[], options: RunOptions = {}): Promise<str
     ? (text: string): string => redactPreservingOpaqueFields(text, opaqueFields, base)
     : base;
 
-  const fullArgs = assembleArgs(args, { account, interactive, readonly });
+  const fullArgs = assembleArgs(args, { account, interactive, readonly, gmailNoSend });
 
   // Redaction wraps the spawn: a successful `gog auth tokens` (or any command
   // echoing a credential) would otherwise return raw Google tokens (ya29.…/1//…)
@@ -511,7 +579,7 @@ export async function run(args: GogArg[], options: RunOptions = {}): Promise<str
 // would corrupt. No redaction: the base64 of a user's own binary file is opaque
 // and has no token shapes to leak.
 export async function runBinary(args: GogArg[], options: RunOptions = {}): Promise<string> {
-  const { account, spawner, timeout, readonly = false } = options;
-  const fullArgs = assembleArgs(args, { account, interactive: false, readonly });
-  return spawnExecutor(fullArgs, { timeout, interactive: false, spawner, binary: true });
+  const { account, spawner, timeout, readonly = false, gmailNoSend = false, maxOutputBytes } = options;
+  const fullArgs = assembleArgs(args, { account, interactive: false, readonly, gmailNoSend });
+  return spawnExecutor(fullArgs, { timeout, interactive: false, spawner, binary: true, maxOutputBytes });
 }