gogcli-mcp 2.23.1 → 2.24.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
-    "version": "2.23.1"
+    "version": "2.24.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli",
       "source": "./",
       "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
-      "version": "2.23.1",
+      "version": "2.24.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp",
   "displayName": "gogcli",
-  "version": "2.23.1",
+  "version": "2.24.0",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",

package/dist/index.js

@@ -31552,6 +31552,55 @@ function normalizeTimestamps(text, tz = displayTimeZone(), naiveTz = naiveSource
   return JSON.stringify(parsed, null, detectIndent(text));
 }
 
+// src/pagination.ts
+function detectIndent2(text) {
+  const match = /\n(\s+)\S/.exec(text);
+  return match ? match[1].replace(/\t/g, "  ").length : 0;
+}
+function stripConsumedPageToken(text) {
+  const trimmed = text.trim();
+  if (trimmed === "" || !trimmed.startsWith("{")) return text;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return text;
+  }
+  const obj = parsed;
+  if (obj.nextPageToken !== "") return text;
+  delete obj.nextPageToken;
+  return JSON.stringify(obj, null, detectIndent2(text));
+}
+function truncationWarning(returned, count) {
+  const scope = count.total !== void 0 ? `returned ${returned} of ${count.total} matches` : count.atLeast !== void 0 ? `returned ${returned} of at least ${count.atLeast} matches` : `returned ${returned} matches and MORE EXIST beyond this page`;
+  return `INCOMPLETE RESULT SET: ${scope}. Do not report an absence of results based on this response. Page with nextPageToken or narrow the query.`;
+}
+function annotateTruncation(out, returned, count) {
+  out.truncated = true;
+  out.returned = returned;
+  if (count.total !== void 0) out.totalMatches = count.total;
+  if (count.atLeast !== void 0) out.totalMatchesAtLeast = count.atLeast;
+  out.warning = truncationWarning(returned, count);
+}
+function hasMorePages(parsed) {
+  return typeof parsed.nextPageToken === "string" && parsed.nextPageToken !== "";
+}
+function annotateTruncatedList(result, itemsKey) {
+  const first = result.content[0];
+  if (result.isError || first?.type !== "text") return result;
+  let parsed;
+  try {
+    parsed = JSON.parse(first.text);
+  } catch {
+    return result;
+  }
+  const items = parsed[itemsKey];
+  if (!Array.isArray(items) || !hasMorePages(parsed)) return result;
+  const out = { ...parsed };
+  annotateTruncation(out, items.length, {});
+  return rawTextResult(JSON.stringify(out));
+}
+
 // src/tools/utils.ts
 var PAYLOAD_INLINE_MAX = 4096;
 function payloadArg(inlineFlag, fileFlag, value, ext) {
@@ -31587,9 +31636,19 @@ var ids = {
   // People API uses fully-qualified resource names ("people/c123") not bare IDs.
   person: external_exports.string().describe("Person resource name (people/...) or email")
 };
+var pageTokenParam = external_exports.string().optional().describe(
+  "Cursor for the NEXT page. Pass back the nextPageToken from a previous response verbatim, keeping the query and max identical: call once, then call again with pageToken=<that value>. A response with NO nextPageToken is the last page."
+);
+var pageAliasParam = external_exports.string().optional().describe(
+  "Deprecated alias for pageToken, accepted so existing callers keep working. Use pageToken \u2014 it matches the nextPageToken field in the response."
+);
+function resolvePageToken(p) {
+  return p.pageToken ?? p.page;
+}
 var paginationParams = {
   max: external_exports.number().int().optional().describe("Max results"),
-  page: external_exports.string().optional().describe("Page token"),
+  pageToken: pageTokenParam,
+  page: pageAliasParam,
   all: external_exports.boolean().optional().describe("Fetch all pages")
 };
 function registerRunTool(server, options) {
@@ -31664,7 +31723,7 @@ ${accounts || "(none)"}${hint}`);
 async function runOrDiagnose(args, options) {
   try {
     const raw = await run(args, options);
-    return rawTextResult(options.lossless ? raw : normalizeTimestamps(raw));
+    return rawTextResult(options.lossless ? raw : stripConsumedPageToken(normalizeTimestamps(raw)));
   } catch (err) {
     return diagnose(err);
   }
@@ -31768,6 +31827,7 @@ function registerApiTools(server) {
 // src/tools/auth.ts
 function registerAuthToolsWith(server, defaultServices) {
   const servicesDescribe = `Services to authorize: "all" or comma-separated list (e.g. "sheets,gmail,calendar"). Default: "${defaultServices}". Prefer the narrowest set you need \u2014 requesting a service whose Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request with invalid_scope.`;
+  const extraScopesDescribe = "Additional raw OAuth scope URIs to request, comma-separated, on top of the ones `services` implies. Use for scopes no service covers \u2014 e.g. https://www.googleapis.com/auth/bigquery.readonly, required before gog_sheets_datasource_* can read BigQuery-backed Connected Sheets. Leave unset otherwise: an extra scope whose API is not enabled on the OAuth client project makes Google reject the WHOLE authorization with invalid_scope.";
   server.registerTool("gog_auth_list", {
     description: "List the Google accounts stored in gogcli, with their scopes. This reads local configuration only \u2014 it does not contact Google and does NOT tell you whether an account still works: a signed-out account whose refresh token expired or was revoked is listed here exactly like a healthy one, scopes and all. Use gog_auth_health to check whether an account can actually authenticate.",
     annotations: { readOnlyHint: true },
@@ -31817,11 +31877,14 @@ function registerAuthToolsWith(server, defaultServices) {
     annotations: { destructiveHint: true },
     inputSchema: {
       email: external_exports.string().describe("Google account email to authorize"),
-      services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe)
+      services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe),
+      extraScopes: external_exports.string().optional().describe(extraScopesDescribe)
     }
-  }, async ({ email: email3, services = defaultServices }) => {
+  }, async ({ email: email3, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(["auth", "add", email3, "--services", services], {
+      const args = ["auth", "add", email3, "--services", services];
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`, "--force-consent");
+      return rawTextResult(await run(args, {
         interactive: true,
         timeout: 3e5
       }));
@@ -31833,14 +31896,14 @@ function registerAuthToolsWith(server, defaultServices) {
     description: "Begin REMOTE/headless Google authorization (step 1 of 2). Returns a sign-in URL to open in any browser \u2014 no local server or terminal on the gogcli host is needed, so this works over the hosted connector where the interactive gog_auth_add cannot. Hand the URL to the user; after they sign in, the browser is redirected to a localhost URL that fails to load \u2014 that is expected. They copy that full redirected URL (from the address bar) and you pass it to gog_auth_add_complete. The link is valid for 10 minutes. If you pass a custom `services` here, pass the SAME value to gog_auth_add_complete or the second step will not match this one.",
     inputSchema: {
       email: external_exports.string().describe("Google account email to authorize"),
-      services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe)
+      services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe),
+      extraScopes: external_exports.string().optional().describe(`${extraScopesDescribe} Pass the SAME value to gog_auth_add_complete.`)
     }
-  }, async ({ email: email3, services = defaultServices }) => {
+  }, async ({ email: email3, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(
-        ["auth", "add", email3, "--remote", "--step", "1", "--services", services, "--force-consent"],
-        { redactMode: "tokens" }
-      ));
+      const args = ["auth", "add", email3, "--remote", "--step", "1", "--services", services, "--force-consent"];
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`);
+      return rawTextResult(await run(args, { redactMode: "tokens" }));
     } catch (err) {
       return errorResult(errorText(err));
     }
@@ -31855,25 +31918,28 @@ function registerAuthToolsWith(server, defaultServices) {
       ),
       services: external_exports.string().optional().default(defaultServices).describe(
         `Services authorized \u2014 MUST match the value passed to gog_auth_add_url. Default: "${defaultServices}".`
+      ),
+      extraScopes: external_exports.string().optional().describe(
+        "Extra OAuth scope URIs \u2014 MUST match the value passed to gog_auth_add_url, for the same reason `services` must: the two steps have to describe the same grant."
       )
     }
-  }, async ({ email: email3, redirectUrl, services = defaultServices }) => {
+  }, async ({ email: email3, redirectUrl, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(
-        [
-          "auth",
-          "add",
-          email3,
-          "--remote",
-          "--step",
-          "2",
-          "--auth-url",
-          redirectUrl,
-          "--services",
-          services,
-          "--force-consent"
-        ]
-      ));
+      const args = [
+        "auth",
+        "add",
+        email3,
+        "--remote",
+        "--step",
+        "2",
+        "--auth-url",
+        redirectUrl,
+        "--services",
+        services,
+        "--force-consent"
+      ];
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`);
+      return rawTextResult(await run(args));
     } catch (err) {
       return errorResult(errorText(err));
     }
@@ -31892,30 +31958,44 @@ function registerAuthTools(server) {
 // src/tools/calendar.ts
 function registerCalendarTools(server) {
   server.registerTool("gog_calendar_events", {
-    description: "List calendar events. Filters can be combined (e.g. --from + --to for a range, or --today for just today).",
+    description: 'List calendar events. Describe the window ONE way and one way only (gog >= 0.36.0 rejects the rest as ambiguous rather than silently discarding a flag): today on its own; or from + to; or from + days; or days on its own (a window of that many days starting today). today cannot be combined with from, to or days, and days cannot be combined with to. gog returns only 10 events by default, so a wide date range is USUALLY INCOMPLETE: raise max, or page with pageToken until the response carries no nextPageToken. A response carrying "truncated": true is an incomplete view \u2014 never conclude an event does not exist from one.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       calendarId: external_exports.string().optional().describe("Calendar ID (default: primary calendar)"),
       from: external_exports.string().optional().describe("Start time filter (RFC3339, date, or natural language)"),
-      to: external_exports.string().optional().describe("End time filter (RFC3339, date, or natural language)"),
-      today: external_exports.boolean().optional().describe("Only show today's events"),
+      to: external_exports.string().optional().describe("End time filter (RFC3339, date, or natural language). Mutually exclusive with today and with days."),
+      // gog >= 0.36.0 (openclaw/gogcli#981). Before that release --days sat in
+      // a switch arm evaluated ahead of --from, so `--from 2026-09-25 --days 5`
+      // silently threw --from away and answered for today instead — at exit 0,
+      // in a well-formed table. It is only exposed here now that it means what
+      // it says.
+      days: external_exports.number().int().positive().optional().describe('Window LENGTH in days (calendar days, DST-aware), measured from `from` when one is given and from today otherwise. Use from + days for "the week of the 25th"; days alone for "the next N days". Mutually exclusive with to and with today.'),
+      today: external_exports.boolean().optional().describe("Only show today's events. A complete window on its own \u2014 mutually exclusive with from, to and days."),
       query: external_exports.string().optional().describe("Free text search within events"),
-      all: external_exports.boolean().optional().describe("Fetch events from all calendars"),
+      max: external_exports.number().int().optional().describe("Max events to return. gog defaults to 10, which silently hides the rest \u2014 raise it, or page with pageToken."),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
+      all: external_exports.boolean().optional().describe('Fetch events from ALL CALENDARS. NOTE: unlike the gmail search tools, this does NOT mean "all pages" \u2014 it widens the calendar set, not the page window. Use pageToken to reach later pages.'),
       eventTypes: external_exports.array(external_exports.enum(["default", "birthday", "focus-time", "from-gmail", "out-of-office", "working-location"])).optional().describe("Filter to specific event types (repeatable)"),
       timezone: external_exports.string().optional().describe(`Display timezone for event times (IANA name, e.g. America/New_York, or "local" for the system timezone). Default: each event's timezone, then its calendar's timezone.`),
       account: accountParam
     }
-  }, async ({ calendarId, from, to, today, query, all, eventTypes, timezone, account }) => {
+  }, async ({ calendarId, from, to, days, today, query, max, pageToken, page, all, eventTypes, timezone, account }) => {
     const args = ["calendar", "events"];
     if (calendarId) args.push(calendarId);
     if (from) args.push(`--from=${from}`);
     if (to) args.push(`--to=${to}`);
+    if (days !== void 0) args.push(`--days=${days}`);
     if (today) args.push("--today");
     if (query) args.push(`--query=${query}`);
+    if (max !== void 0) args.push(`--max=${max}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     if (eventTypes) for (const t of eventTypes) args.push(`--event-types=${t}`);
     if (timezone) args.push(`--timezone=${timezone}`);
-    return runOrDiagnose(args, { account });
+    const result = await runOrDiagnose(args, { account });
+    return annotateTruncatedList(result, "events");
   });
   server.registerTool("gog_calendar_get", {
     description: "Get a specific calendar event by ID.",
@@ -32032,17 +32112,19 @@ function registerClassroomTools(server) {
       teacher: external_exports.string().optional().describe("Filter by teacher user ID"),
       student: external_exports.string().optional().describe("Filter by student user ID"),
       max: external_exports.number().optional().describe("Max results per page"),
-      page: external_exports.string().optional().describe("Page token for pagination"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       account: accountParam
     }
-  }, async ({ state, teacher, student, max, page, all, account }) => {
+  }, async ({ state, teacher, student, max, pageToken, page, all, account }) => {
     const args = ["classroom", "courses", "list"];
     if (state) args.push(`--state=${state}`);
     if (teacher) args.push(`--teacher=${teacher}`);
     if (student) args.push(`--student=${student}`);
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     return runOrDiagnose(args, { account });
   });
@@ -32062,14 +32144,16 @@ function registerClassroomTools(server) {
     inputSchema: {
       courseId: external_exports.string().describe("Course ID"),
       max: external_exports.number().optional().describe("Max results per page"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       account: accountParam
     }
-  }, async ({ courseId, max, page, all, account }) => {
+  }, async ({ courseId, max, pageToken, page, all, account }) => {
     const args = ["classroom", "students", "list", courseId];
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     return runOrDiagnose(args, { account });
   });
@@ -32090,14 +32174,16 @@ function registerClassroomTools(server) {
     inputSchema: {
       courseId: external_exports.string().describe("Course ID"),
       max: external_exports.number().optional().describe("Max results per page"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       account: accountParam
     }
-  }, async ({ courseId, max, page, all, account }) => {
+  }, async ({ courseId, max, pageToken, page, all, account }) => {
     const args = ["classroom", "teachers", "list", courseId];
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     return runOrDiagnose(args, { account });
   });
@@ -32120,16 +32206,18 @@ function registerClassroomTools(server) {
       students: external_exports.boolean().optional().describe("Include students only"),
       teachers: external_exports.boolean().optional().describe("Include teachers only"),
       max: external_exports.number().optional().describe("Max results per page"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       account: accountParam
     }
-  }, async ({ courseId, students, teachers, max, page, all, account }) => {
+  }, async ({ courseId, students, teachers, max, pageToken, page, all, account }) => {
     const args = ["classroom", "roster", courseId];
     if (students) args.push("--students");
     if (teachers) args.push("--teachers");
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     return runOrDiagnose(args, { account });
   });
@@ -32142,18 +32230,20 @@ function registerClassroomTools(server) {
       topic: external_exports.string().optional().describe("Filter by topic ID"),
       orderBy: external_exports.string().optional().describe('Sort order (e.g. "updateTime desc")'),
       max: external_exports.number().optional().describe("Max results per page"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       scanPages: external_exports.number().optional().describe("Max pages to scan when filtering"),
       account: accountParam
     }
-  }, async ({ courseId, state, topic, orderBy, max, page, all, scanPages, account }) => {
+  }, async ({ courseId, state, topic, orderBy, max, pageToken, page, all, scanPages, account }) => {
     const args = ["classroom", "coursework", "list", courseId];
     if (state) args.push(`--state=${state}`);
     if (topic) args.push(`--topic=${topic}`);
     if (orderBy) args.push(`--order-by=${orderBy}`);
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     if (scanPages !== void 0) args.push(`--scan-pages=${scanPages}`);
     return runOrDiagnose(args, { account });
@@ -32179,17 +32269,19 @@ function registerClassroomTools(server) {
       late: external_exports.enum(["late", "not-late"]).optional().describe("Filter by late status"),
       user: external_exports.string().optional().describe("Filter by student user ID"),
       max: external_exports.number().optional().describe("Max results per page"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       account: accountParam
     }
-  }, async ({ courseId, courseworkId, state, late: late2, user, max, page, all, account }) => {
+  }, async ({ courseId, courseworkId, state, late: late2, user, max, pageToken, page, all, account }) => {
     const args = ["classroom", "submissions", "list", courseId, courseworkId];
     if (state) args.push(`--state=${state}`);
     if (late2) args.push(`--late=${late2}`);
     if (user) args.push(`--user=${user}`);
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     return runOrDiagnose(args, { account });
   });
@@ -32266,16 +32358,18 @@ function registerClassroomTools(server) {
       state: external_exports.string().optional().describe("Filter by announcement state"),
       orderBy: external_exports.string().optional().describe("Sort order"),
       max: external_exports.number().optional().describe("Max results per page"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       account: accountParam
     }
-  }, async ({ courseId, state, orderBy, max, page, all, account }) => {
+  }, async ({ courseId, state, orderBy, max, pageToken, page, all, account }) => {
     const args = ["classroom", "announcements", "list", courseId];
     if (state) args.push(`--state=${state}`);
     if (orderBy) args.push(`--order-by=${orderBy}`);
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     return runOrDiagnose(args, { account });
   });
@@ -32311,14 +32405,16 @@ function registerClassroomTools(server) {
     inputSchema: {
       courseId: external_exports.string().describe("Course ID"),
       max: external_exports.number().optional().describe("Max results per page"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       account: accountParam
     }
-  }, async ({ courseId, max, page, all, account }) => {
+  }, async ({ courseId, max, pageToken, page, all, account }) => {
     const args = ["classroom", "topics", "list", courseId];
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     return runOrDiagnose(args, { account });
   });
@@ -32340,16 +32436,18 @@ function registerClassroomTools(server) {
       course: external_exports.string().optional().describe("Filter by course ID"),
       user: external_exports.string().optional().describe("Filter by user ID"),
       max: external_exports.number().optional().describe("Max results per page"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       account: accountParam
     }
-  }, async ({ course, user, max, page, all, account }) => {
+  }, async ({ course, user, max, pageToken, page, all, account }) => {
     const args = ["classroom", "invitations", "list"];
     if (course) args.push(`--course=${course}`);
     if (user) args.push(`--user=${user}`);
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     return runOrDiagnose(args, { account });
   });
@@ -32559,16 +32657,18 @@ function registerDriveTools(server) {
     inputSchema: {
       folderId: external_exports.string().optional().describe("Folder ID to list (default: root)"),
       max: external_exports.number().optional().describe("Max results (default: 20)"),
-      page: external_exports.string().optional().describe("Page token for pagination"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       query: external_exports.string().optional().describe(`Drive query filter (e.g. "name contains 'budget'")`),
       allDrives: external_exports.boolean().optional().describe("Include shared drives (default: true). Set false for My Drive only."),
       account: accountParam
     }
-  }, async ({ folderId, max, page, query, allDrives, account }) => {
+  }, async ({ folderId, max, pageToken, page, query, allDrives, account }) => {
     const args = ["drive", "ls"];
     if (folderId) args.push(`--parent=${folderId}`);
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (query) args.push(`--query=${query}`);
     if (allDrives === false) args.push("--no-all-drives");
     return runOrDiagnose(args, { account });
@@ -32758,34 +32858,148 @@ function registerDriveTools(server) {
   registerRunTool(server, { service: "drive", examples: '"copy", "upload", "download", "permissions"' });
 }
 
+// src/gmail-results.ts
+function sortKey(item) {
+  for (const raw of [item.internalDateIso, item.date]) {
+    if (typeof raw !== "string" || !raw) continue;
+    const t = Date.parse(raw);
+    if (!Number.isNaN(t)) return t;
+  }
+  return Number.NEGATIVE_INFINITY;
+}
+function sortNewestFirst(items) {
+  return [...items].sort((a, b) => {
+    const ka = sortKey(a);
+    const kb = sortKey(b);
+    return ka === kb ? 0 : kb - ka;
+  });
+}
+var COUNT_PROBE_PAGE_SIZE = 500;
+async function countMatches(method, itemsKey, query, account) {
+  try {
+    const params = JSON.stringify({
+      userId: "me",
+      q: query,
+      maxResults: COUNT_PROBE_PAGE_SIZE,
+      fields: `${itemsKey}/id,nextPageToken`
+    });
+    const raw = await run(["api", "call", "gmail", "v1", method, `--params=${params}`], { account });
+    const parsed = JSON.parse(raw);
+    const items = parsed[itemsKey];
+    if (!Array.isArray(items)) return {};
+    const more = typeof parsed.nextPageToken === "string" && parsed.nextPageToken !== "";
+    return more ? { atLeast: items.length } : { total: items.length };
+  } catch {
+    return {};
+  }
+}
+async function finalizeGmailSearch(result, options) {
+  const { itemsKey, method, query, account, queryIsExact = true } = options;
+  const first = result.content[0];
+  if (result.isError || first?.type !== "text") return result;
+  let parsed;
+  try {
+    parsed = JSON.parse(first.text);
+  } catch {
+    return result;
+  }
+  const items = parsed[itemsKey];
+  if (!Array.isArray(items)) return result;
+  const sorted = sortNewestFirst(items);
+  const out = { ...parsed, [itemsKey]: sorted };
+  if (hasMorePages(parsed)) {
+    const count = queryIsExact ? await countMatches(method, itemsKey, query, account) : {};
+    annotateTruncation(out, sorted.length, count);
+  }
+  return rawTextResult(JSON.stringify(out));
+}
+async function fetchGmailPages(runPage, itemsKey, maxPages, startToken) {
+  const merged = [];
+  let base;
+  let token = startToken;
+  for (let pages = 0; pages < maxPages; pages++) {
+    const result = await runPage(token);
+    const parsed = parsePage(result, itemsKey);
+    if (parsed === void 0) {
+      return base === void 0 ? result : finish(base, itemsKey, merged, token);
+    }
+    base = parsed;
+    merged.push(...parsed[itemsKey]);
+    token = typeof parsed.nextPageToken === "string" && parsed.nextPageToken !== "" ? parsed.nextPageToken : void 0;
+    if (token === void 0) break;
+  }
+  return finish(base, itemsKey, merged, token);
+}
+function parsePage(result, itemsKey) {
+  const first = result.content[0];
+  if (result.isError || first?.type !== "text") return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(first.text);
+  } catch {
+    return void 0;
+  }
+  if (parsed === null || typeof parsed !== "object") return void 0;
+  const obj = parsed;
+  return Array.isArray(obj[itemsKey]) ? obj : void 0;
+}
+function finish(base, itemsKey, merged, token) {
+  const out = { ...base, [itemsKey]: merged };
+  if (token === void 0) delete out.nextPageToken;
+  else out.nextPageToken = token;
+  return rawTextResult(JSON.stringify(out));
+}
+
 // src/tools/gmail.ts
 function registerGmailTools(server) {
   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).`,
+    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). Results are ALWAYS newest-first by Gmail\'s internalDate \u2014 the wrapper sorts them, so the first result is the most recent match and a recent message can never be buried below older ones. IMPORTANT \u2014 a response carrying "truncated": true is an INCOMPLETE view of the matches: NEVER report that a message does not exist, or that there is no such mail, on the strength of one. Page through it (pass nextPageToken back as `pageToken`), set maxPages to walk several pages in one call, or narrow the query, and only then draw a conclusion. If you already know the thread, do not search for it at all \u2014 read it directly with gog_gmail_thread_get, which returns the whole thread and cannot be truncated or mis-ranked.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       query: external_exports.string().describe("Gmail search query"),
       max: external_exports.number().int().optional().describe("Max results to return (default: 10)"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
+      maxPages: external_exports.number().int().positive().max(20).optional().describe('Walk up to this many pages in ONE call and merge the results, instead of returning a single page. Use it for existence questions ("is there any mail matching X?"), which a single page cannot answer. Stops early at the last page; if pages remain when the cap is hit the response is still marked truncated. Prefer this over all=true, which is unbounded.'),
+      all: external_exports.boolean().optional().describe('Fetch every page instead of one. Removes truncation entirely, at the cost of one API round-trip per page \u2014 the reliable way to answer "does any message match?" for a query with few expected hits.'),
       fromContact: external_exports.string().optional().describe("Resolve a Google Contact (name or email) to its addresses and AND a from:(addr OR addr) clause onto the query \u2014 saves looking the contact up first when you only know who, not which address."),
       account: accountParam
     }
-  }, async ({ query, max, fromContact, account }) => {
+  }, async ({ query, max, pageToken, page, maxPages, all, fromContact, account }) => {
     const args = ["gmail", "search", query];
     if (max !== void 0) args.push(`--max=${max}`);
+    if (all) args.push("--all");
     if (fromContact) args.push(`--from-contact=${fromContact}`);
-    return runOrDiagnose(args, { account });
+    const runPage = (tok) => runOrDiagnose(tok ? [...args, `--page=${tok}`] : args, { account });
+    const token = resolvePageToken({ pageToken, page });
+    const result = maxPages !== void 0 ? await fetchGmailPages(runPage, "threads", maxPages, token) : await runPage(token);
+    return finalizeGmailSearch(result, {
+      itemsKey: "threads",
+      method: "users.threads.list",
+      query,
+      account,
+      // --from-contact is expanded INSIDE gog, against the People API, so the
+      // query Gmail actually saw is not the one we hold here.
+      queryIsExact: !fromContact
+    });
   });
   server.registerTool("gog_gmail_get", {
-    description: "Get a Gmail message by ID.",
+    description: "Get a Gmail message by ID. For a long message, sanitizeContent is the cheapest way to keep it in context: it drops the raw MIME payload and the HTML part, which are usually the bulk of the response.",
     annotations: { readOnlyHint: true },
     inputSchema: {
       messageId: external_exports.string().describe("Message ID"),
       format: external_exports.enum(["full", "metadata", "raw"]).optional().describe("Message format (default: full)"),
+      // Requires gog >= 0.37.0. Before that (openclaw/gogcli#992) the JSON
+      // carried the headers and body TWICE — once inside `message`, once
+      // copied to the top level — so the flag meant to shrink the payload
+      // enlarged it. MIN_GOG_VERSION is the guard; there is no runtime check.
+      sanitizeContent: external_exports.boolean().optional().describe("Return agent-oriented sanitized content: HTML stripped, HTTP(S) URLs removed, raw Gmail payloads omitted from the JSON. The largest payload-size reduction available here. Note the URL removal is lossy \u2014 omit this when you need to follow a link out of the message."),
       account: accountParam
     }
-  }, async ({ messageId, format, account }) => {
+  }, async ({ messageId, format, sanitizeContent, account }) => {
     const args = ["gmail", "get", messageId];
     if (format) args.push(`--format=${format}`);
+    if (sanitizeContent) args.push("--sanitize-content");
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_gmail_send", {
@@ -33138,7 +33352,7 @@ function registerTasksTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "2.23.1" : "0.0.0";
+var VERSION = true ? "2.24.0" : "0.0.0";
 var BASE_TOOL_REGISTRARS = [
   registerApiTools,
   registerAuthTools,