gogcli-mcp 4.2.5 → 4.3.0

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "4.2.5",
+  "version": "4.3.0",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",
@@ -37,7 +37,8 @@
       ],
       "env": {
         "GOG_ACCOUNT": "${user_config.gog_account}",
-        "GOG_PATH": "${user_config.gog_path}"
+        "GOG_PATH": "${user_config.gog_path}",
+        "GOG_FILE_ROOTS": "${user_config.gog_file_roots}"
       }
     }
   },
@@ -53,6 +54,12 @@
       "title": "gog Executable Path",
       "description": "Path to the gog executable (optional — defaults to 'gog' on your PATH)",
       "required": false
+    },
+    "gog_file_roots": {
+      "type": "string",
+      "title": "Allowed file directories",
+      "description": "Directories tools may read files from (attachments, uploads) or write files to (exports, downloads), separated by ':' (';' on Windows). Optional — defaults to ~/gogcli-mcp-files",
+      "required": false
     }
   },
   "tools": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "4.2.5",
+  "version": "4.3.0",
   "mcpName": "io.github.chrischall/gogcli-mcp",
   "description": "MCP server wrapping gogcli for Google service access",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -41,7 +41,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.1.0",
+    "@chrischall/mcp-utils": "^2.4.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.6.1"
   },

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp"
   },
-  "version": "4.2.5",
+  "version": "4.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp",
-      "version": "4.2.5",
+      "version": "4.3.0",
       "transport": {
         "type": "stdio"
       },

package/src/arg-guard.ts

@@ -0,0 +1,68 @@
+// Guards for argv this wrapper does NOT build itself.
+//
+// The `gog_<service>_run` escape hatches forward a model-supplied string[]
+// verbatim. gog (kong) takes the LAST value of a repeated flag, so an arg like
+// `--readonly=false` placed after the runner's injected `--readonly` silently
+// re-enables writes on a deployment the operator locked read-only — the one
+// kill switch an operator can set (audit SEC-1). The same holds for every
+// other global that is a control rather than an option: the command allow/deny
+// lists, the credential source (`--access-token`, `--home`, `--client`), the
+// account, `--gmail-no-send` and `--no-input`.
+//
+// A bare `--` is refused as well. It ends flag parsing, so anything the wrapper
+// appends AFTER it (a safety flag appended last, for instance) would be read as
+// a positional and quietly dropped.
+//
+// Kept out of runner.ts on purpose: tool tests automock the runner module, and
+// these checks have to run for real inside the tool handlers.
+
+// Long-flag names whose override the model must never control, matched as
+// EXACT names: the flag alone (`--readonly`) or with an attached value
+// (`--readonly=false`), case-insensitively. Not as bare prefixes — that refused
+// legitimate command flags that merely share a leading word, such as
+// gog_zoom_auth_setup's --account-id / --client-id / --client-secret. gog has
+// no flag abbreviation, so a longer spelling is a different flag, not an
+// override.
+const FORBIDDEN_LONG_FLAG = /^--(readonly|enable-commands|enable-commands-exact|disable-commands|access-token|home|account|acct|client|gmail-no-send|no-input|non-interactive|noninteractive)(=|$)/i;
+
+// `-a` is the short form of --account. kong accepts short-flag CLUSTERS
+// (`-ja` = `-j -a`) and an attached value (`-aother@x`), so any single-dash
+// token whose letters include `a` is refused. `-5` (a negative number) and
+// `-y` (force) are unaffected.
+const SHORT_ACCOUNT_CLUSTER = /^-(?!-)[A-Za-z]*a/;
+
+/** Why `arg` may not be forwarded to gog, or undefined when it is fine. */
+export function forbiddenArgReason(arg: string): string | undefined {
+  if (arg === '--') {
+    return 'The argument "--" is not allowed: it ends flag parsing and would disable safety flags appended after it.';
+  }
+  const match = FORBIDDEN_LONG_FLAG.exec(arg);
+  if (match) {
+    return `The flag ${arg} is not allowed here: --${match[1].toLowerCase()} is a safety/credential control set by the server operator, not a per-call option.`;
+  }
+  if (SHORT_ACCOUNT_CLUSTER.test(arg)) {
+    return `The flag ${arg} is not allowed here: -a selects the account. Use the tool's account parameter instead.`;
+  }
+  return undefined;
+}
+
+/** Throw on the first model-supplied arg that would override a gog safety control. */
+export function assertSafeForwardedArgs(args: readonly string[]): void {
+  for (const arg of args) {
+    const reason = forbiddenArgReason(arg);
+    if (reason) throw new Error(reason);
+  }
+}
+
+// A gog subcommand is a lower-case word, possibly hyphenated (`mark-read`).
+// Anything else — a flag, an empty string, a path — is a smuggling attempt or a
+// mistake, and gog would parse it as something other than a subcommand.
+const SUBCOMMAND_SHAPE = /^[a-z][a-z0-9-]*$/;
+
+export function assertSafeSubcommand(subcommand: string): void {
+  if (!SUBCOMMAND_SHAPE.test(subcommand)) {
+    throw new Error(
+      `Invalid subcommand ${JSON.stringify(subcommand)}: pass a single gog subcommand name such as "list" or "mark-read", and put its arguments in args.`,
+    );
+  }
+}

package/src/argv.ts

@@ -0,0 +1,27 @@
+// Positional-argument marking for gog argv (audit BUG-1).
+//
+// A tool's positional values — a Gmail query, a file ID, a range, a name — are
+// chosen by the model. Pushed as bare argv elements, one that starts with '-'
+// is parsed by gog (kong) as a flag: `gog gmail search "-in:spam"` fails with
+// "unknown flag -i", and a value starting with `--` becomes a real gog flag.
+// Wrapping each value in pos() tells the runner to place it after a single
+// `--`, after every flag, which is how upstream gogcli's own MCP tools call it
+// (internal/cmd/mcp_tools.go).
+//
+// Lives outside runner.ts on purpose: tool tests automock the runner module,
+// and pos() must stay a real function there.
+
+export interface GogPositional {
+  /** Discriminant separating this from a plain argv string and a GogFileArg. */
+  kind: 'positional';
+  value: string;
+}
+
+/** Mark a model-supplied positional value so it is passed after `--`. */
+export function pos(value: string): GogPositional {
+  return { kind: 'positional', value };
+}
+
+export function isGogPositional(arg: unknown): arg is GogPositional {
+  return typeof arg === 'object' && arg !== null && (arg as { kind?: unknown }).kind === 'positional';
+}

package/src/attachment-root.ts

@@ -0,0 +1,111 @@
+// The private, self-cleaning directory attachment downloads land in (audit SEC-6).
+//
+// It used to be a fixed `/tmp/gog-attachments` that nothing ever emptied, so
+// every downloaded attachment — medical records, statements, custody documents
+// — piled up in world-traversable /tmp for the life of the host. And because
+// the name was predictable and shared, another local user could pre-create it
+// or plant a symlink there, redefining where the blob-upload "confinement"
+// root pointed.
+//
+// Now the root is per-user (named for the uid, under the OS temp dir), created
+// owner-only (0700), and verified before every use: a symlink, a non-directory
+// or a directory owned by someone else is refused rather than trusted. Files a
+// caller never sees again (inline, Drive and URL deliveries) are deleted as
+// soon as they are delivered; files returned BY PATH are kept for the caller to
+// read and swept once they are older than ATTACHMENT_TTL_MS.
+
+import { tmpdir, userInfo } from 'node:os';
+import { dirname, join, relative, resolve, isAbsolute, sep } from 'node:path';
+
+/** Where gmail attachment downloads are written, and the only tree the blob upload reads from. */
+export const ATTACHMENT_DOWNLOAD_ROOT = join(tmpdir(), `gogcli-mcp-attachments-${userInfo().uid}`);
+
+/** How long a download returned by path is kept before a later download sweeps it. */
+export const ATTACHMENT_TTL_MS = 24 * 60 * 60 * 1000;
+
+function isInside(root: string, target: string): boolean {
+  const rel = relative(root, target);
+  return rel !== '' && !rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel);
+}
+
+/**
+ * Create `dir` owner-only if missing, then verify it: a real directory (not a
+ * symlink), owned by this user, with no group/other permissions (tightened to
+ * 0700 when it is ours but looser). `opts.uid` is injected by tests.
+ */
+export async function ensurePrivateDir(dir: string, opts: { uid?: number } = {}): Promise<void> {
+  const { mkdir, lstat, chmod } = await import('node:fs/promises');
+  try {
+    await mkdir(dir, { mode: 0o700 });
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+  }
+  const info = await lstat(dir);
+  if (info.isSymbolicLink() || !info.isDirectory()) {
+    throw new Error(`refusing to use ${dir} for attachment downloads: it is not a real directory`);
+  }
+  const uid = opts.uid ?? userInfo().uid;
+  if (info.uid !== uid) {
+    throw new Error(`refusing to use ${dir} for attachment downloads: it is owned by another user`);
+  }
+  if ((info.mode & 0o077) !== 0) await chmod(dir, 0o700);
+}
+
+/**
+ * Delete top-level entries of `root` last modified more than `ttlMs` ago.
+ * Best-effort: a missing root sweeps nothing, and one entry failing never stops
+ * the rest. Returns how many entries were removed.
+ */
+export async function sweepExpiredDownloads(
+  root: string = ATTACHMENT_DOWNLOAD_ROOT,
+  ttlMs: number = ATTACHMENT_TTL_MS,
+  now: number = Date.now(),
+): Promise<number> {
+  const { readdir, lstat, rm } = await import('node:fs/promises');
+  let entries: string[];
+  try {
+    entries = await readdir(root);
+  } catch {
+    return 0;
+  }
+  let removed = 0;
+  for (const name of entries) {
+    const path = join(root, name);
+    try {
+      const info = await lstat(path);
+      if (now - info.mtimeMs > ttlMs) {
+        await rm(path, { recursive: true, force: true });
+        removed += 1;
+      }
+    } catch {
+      // raced with another sweep or a delivery cleanup — nothing to do
+    }
+  }
+  return removed;
+}
+
+/**
+ * Delete one delivered download, then any directories it leaves empty, up to
+ * (never including) `root`. A path outside `root` is left alone: this only
+ * ever cleans up after the server's own downloads, never a caller's `out`.
+ */
+export async function removeDownload(path: string, root: string = ATTACHMENT_DOWNLOAD_ROOT): Promise<void> {
+  const { rm, rmdir } = await import('node:fs/promises');
+  const base = resolve(root);
+  const target = resolve(base, path);
+  if (!isInside(base, target)) return;
+  await rm(target, { force: true });
+  for (let dir = dirname(target); isInside(base, dir); dir = dirname(dir)) {
+    try {
+      await rmdir(dir);
+    } catch {
+      break; // not empty (or already gone): stop climbing
+    }
+  }
+}
+
+/** Make the download root private and sweep expired downloads out of it. */
+export async function prepareDownloadRoot(root: string = ATTACHMENT_DOWNLOAD_ROOT): Promise<void> {
+  await ensurePrivateDir(root);
+  await sweepExpiredDownloads(root);
+}

package/src/attachments.ts

@@ -80,6 +80,7 @@ export const MAX_INLINE_ATTACHMENT_TOTAL_BYTES = Math.floor((MAX_REQUEST_PAYLOAD
  */
 function wireBytesOf(arg: GogArg): number {
   if (typeof arg === 'string') return Buffer.byteLength(arg, 'utf8');
+  if (arg.kind === 'positional') return Buffer.byteLength(arg.value, 'utf8');
   return arg.encoding === 'base64' ? arg.contents.length : Buffer.byteLength(arg.contents, 'utf8');
 }
 

package/src/blob-upload.ts

@@ -25,9 +25,11 @@
 /**
  * Where gmail's attachment download writes (`defaultOutPath` in
  * packages/gogcli-mcp-gmail/src/tools/gmail-extra.ts) and the only tree this
- * module will read back from.
+ * module will read back from. Per-user and private — see attachment-root.ts.
  */
-export const ATTACHMENT_DOWNLOAD_ROOT = '/tmp/gog-attachments';
+import { ATTACHMENT_DOWNLOAD_ROOT } from './attachment-root.js';
+
+export { ATTACHMENT_DOWNLOAD_ROOT };
 
 /** mcp-host's blob store caps one object at 100 MiB and answers 413 past it. */
 export const MAX_BLOB_UPLOAD_BYTES = 100 * 1024 * 1024;

package/src/file-roots.ts

@@ -0,0 +1,66 @@
+// Operator-configured confinement for every server-side path a tool accepts
+// (audit SEC-3/SEC-4).
+//
+// `attach`, `localPath`, `file`, `out`, `outDir` and friends are resolved on the
+// machine gog runs on, and the model chooses them. Unconfined, each is a read
+// primitive (attach ~/.ssh/id_rsa, gog's credentials, /proc/<pid>/environ to an
+// email) or a write primitive (drop attacker-chosen attachment bytes on
+// ~/Library/LaunchAgents/x.plist or ~/.zshrc). Every such path must now resolve
+// — through symlinks, via mcp-utils' assertPathWithinRoots — inside one of the
+// directories the operator lists in GOG_FILE_ROOTS, or the server's own private
+// attachment download directory.
+//
+// GOG_FILE_ROOTS is a PATH-style list (':' on POSIX). Unset, it defaults to
+// ~/gogcli-mcp-files: files to attach or upload go there, and exports and
+// downloads with an explicit path must be written there. Set it to a wider
+// directory (e.g. your home) deliberately, not by default.
+
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { assertPathWithinRoots, readEnvVar } from '@chrischall/mcp-utils';
+import { ATTACHMENT_DOWNLOAD_ROOT } from './attachment-root.js';
+
+export const FILE_ROOTS_ENV = 'GOG_FILE_ROOTS';
+
+/** The default root when GOG_FILE_ROOTS is unset. */
+export function defaultFileRoot(): string {
+  return join(homedir(), 'gogcli-mcp-files');
+}
+
+/** The operator's configured roots, or the default one. */
+export function fileRoots(): string[] {
+  const raw = readEnvVar(FILE_ROOTS_ENV);
+  const roots = (raw ?? '').split(delimiter).map((r) => r.trim()).filter(Boolean);
+  return roots.length > 0 ? roots : [defaultFileRoot()];
+}
+
+/**
+ * Require `path` (a model-supplied server path, named `param` in the error) to
+ * lie inside an allowed root. Returns it unchanged. `allowDash` admits gog's
+ * `-` for tools where it means stdout; anywhere else `-` means stdin, which this
+ * server never writes to, so it is refused like any other stray path.
+ */
+export function confinePath(path: string, param: string, opts: { allowDash?: boolean } = {}): string {
+  if (opts.allowDash && path === '-') return path;
+  const roots = [...fileRoots(), ATTACHMENT_DOWNLOAD_ROOT];
+  try {
+    assertPathWithinRoots(path, roots);
+  } catch {
+    throw new Error(
+      `${param} ${JSON.stringify(path)} is outside the directories this server may read or write `
+      + `(${roots.join(', ')}). Put the file in one of them, or ask the server operator to widen ${FILE_ROOTS_ENV}.`,
+    );
+  }
+  return path;
+}
+
+/** confinePath for every element of an optional list. */
+export function confinePaths(paths: readonly string[] | undefined, param: string): void {
+  for (const path of paths ?? []) confinePath(path, param);
+}
+
+/** For JSON-or-`@file` inputs: confine the path of an `@file` value, pass inline JSON through. */
+export function confineAtFile(value: string, param: string): string {
+  if (value.startsWith('@')) confinePath(value.slice(1), param);
+  return value;
+}

package/src/gmail-dispatch-guard.ts

@@ -2,9 +2,9 @@ import type { CallToolResult, InputRequiredResult, ServerContext } from '@modelc
 import { readEnvVar, requireConfirmation } from '@chrischall/mcp-utils';
 
 // ============================================================================
-// 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
@@ -26,7 +26,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 +41,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 +57,8 @@ export const GMAIL_DISPATCH_OPS: readonly GmailDispatchOp[] = [
   'gmail.reply-all',
   'gmail.forward',
   'gmail.autoreply',
+  'gmail.drafts-send',
+  'gmail.filter-forward',
 ];
 
 /**
@@ -66,9 +75,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,6 +92,34 @@ const STAGING_TWIN: Partial<Record<GmailDispatchOp, string>> = {
   'gmail.send': 'gog_gmail_drafts_create',
 };
 
+// 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.',
+};
+
+// Bound on the body text shown in a confirmation prompt. Enough to read what is
+// actually being sent (the point of SEC-5), small enough to keep the prompt a
+// prompt rather than a copy of the message.
+export const BODY_PREVIEW_MAX = 2048;
+
+/** The first BODY_PREVIEW_MAX characters of a body, marked when cut. */
+export function bodyPreview(text: string | undefined): string | undefined {
+  if (!text) return undefined;
+  if (text.length <= BODY_PREVIEW_MAX) return text;
+  return `${text.slice(0, BODY_PREVIEW_MAX)}… [${text.length - BODY_PREVIEW_MAX} more characters not shown]`;
+}
+
+/**
+ * Every attachment a dispatch will carry: a server path in full (so the user
+ * sees WHICH file on the gog host is leaving), an inline one by its filename.
+ */
+export function attachmentNames(
+  paths: readonly string[] | undefined,
+  inline: ReadonlyArray<{ filename: string }> | undefined,
+): string[] {
+  return [...(paths ?? []), ...(inline ?? []).map((a) => a.filename)];
+}
+
 /** Apply the shared stateless confirmation flow with Gmail-specific copy. */
 export function requireGmailDispatchConfirmation(
   ctx: ServerContext,
@@ -90,17 +127,20 @@ export function requireGmailDispatchConfirmation(
   details: Record<string, unknown>,
 ): InputRequiredResult | CallToolResult | undefined {
   const twin = STAGING_TWIN[op];
+  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 requireConfirmation(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.',
+    ...(note ? { unsupportedNote: note } : {}),
   });
 }
 

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,6 +26,8 @@ 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 {
+  attachmentNames,
+  bodyPreview,
   extractEmails,
   logGmailDispatch,
   requireGmailDispatchConfirmation,
@@ -45,6 +47,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.