gogcli-mcp 2.23.2 → 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.2"
+    "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.2",
+      "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.2",
+  "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

@@ -31827,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 },
@@ -31876,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
       }));
@@ -31892,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));
     }
@@ -31914,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));
     }
@@ -31951,13 +31958,19 @@ 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). 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.',
+    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"),
       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,
@@ -31967,11 +31980,12 @@ function registerCalendarTools(server) {
       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, max, pageToken, page, 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}`);
@@ -32970,16 +32984,22 @@ function registerGmailTools(server) {
     });
   });
   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", {
@@ -33332,7 +33352,7 @@ function registerTasksTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "2.23.2" : "0.0.0";
+var VERSION = true ? "2.24.0" : "0.0.0";
 var BASE_TOOL_REGISTRARS = [
   registerApiTools,
   registerAuthTools,

package/dist/lib.js

@@ -23042,7 +23042,7 @@ function activeExecutor() {
   return runExecutor.getStore() ?? defaultExecutor;
 }
 var TIMEOUT_MS = 3e4;
-var MIN_GOG_VERSION = "0.35.0";
+var MIN_GOG_VERSION = "0.37.0";
 function readonlyEnvEnabled() {
   return readEnvVar("GOG_READONLY") !== void 0 && parseBoolEnv("GOG_READONLY", { default: true });
 }
@@ -23712,6 +23712,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 },
@@ -23761,11 +23762,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
       }));
@@ -23777,14 +23781,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));
     }
@@ -23799,25 +23803,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));
     }
@@ -23839,13 +23846,19 @@ function authToolsFor(defaultServices) {
 // 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). 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.',
+    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"),
       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,
@@ -23855,11 +23868,12 @@ function registerCalendarTools(server) {
       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, max, pageToken, page, 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}`);
@@ -24858,16 +24872,22 @@ function registerGmailTools(server) {
     });
   });
   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", {
@@ -25220,7 +25240,7 @@ function registerTasksTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "2.23.2" : "0.0.0";
+var VERSION = true ? "2.24.0" : "0.0.0";
 var BASE_TOOL_REGISTRARS = [
   registerApiTools,
   registerAuthTools,

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "2.23.2",
+  "version": "2.24.0",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "2.23.2",
+  "version": "2.24.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>",

package/server.json

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

package/src/gmail-results.ts

@@ -71,10 +71,21 @@ const COUNT_PROBE_PAGE_SIZE = 500;
 // a caller is most likely to draw a false negative from. A full page with more
 // behind it yields an honest lower bound instead.
 //
-// gog cannot supply this itself: `gmail search` and `gmail messages search`
-// build their JSON by hand from the items plus nextPageToken, so a direct
-// Discovery call is the only route. It is only ever spent on a result set
-// already known to be truncated.
+// gog CAN now supply this itself — `--count` on `gmail search` / `gmail
+// messages search` (gog >= 0.36.0, openclaw/gogcli#985) is this same probe,
+// upstreamed, down to the page size and the exact/lower-bound split. The probe
+// stays here anyway, for two differences that both matter at this seam:
+//
+//   * It is spent ONLY on a result set already known to be truncated. --count
+//     is decided before the search runs, so adopting it would cost every
+//     search an extra Gmail request to answer a question most of them never
+//     raise.
+//   * It is best-effort. gog returns the count probe's error from the whole
+//     command, so a failed count would turn a search that DID succeed into an
+//     error — trading a missing warning for a missing answer.
+//
+// Keep the two in step: a change to what "exact" means on either side should
+// be made on both.
 //
 // Best-effort by construction: any failure must degrade the warning, never the
 // search.

package/src/runner.ts

@@ -167,7 +167,7 @@ const TIMEOUT_MS = 30_000;
 // so the requirement change is surfaced in the release notes (see
 // .github/release.yml). This is the single source of truth for the required
 // version; keep the README/CLAUDE.md mention in sync.
-export const MIN_GOG_VERSION = '0.35.0';
+export const MIN_GOG_VERSION = '0.37.0';
 
 // Interpret the GOG_READONLY kill-switch. `readEnvVar` already treats blank
 // values, 'undefined'/'null' sentinels, and unresolved .mcpb placeholders

package/src/tools/auth.ts

@@ -13,6 +13,20 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     `Default: "${defaultServices}". Prefer the narrowest set you need — requesting a service whose ` +
     `Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request ` +
     `with invalid_scope.`;
+  // Additional raw OAuth scope URIs, appended after the service scopes gog
+  // derives from `services`. This exists for scopes no service selection can
+  // ask for: notably bigquery.readonly, which Google demands whenever a Sheets
+  // response CONTAINS BigQuery Connected Sheets data (gog_sheets_datasource_*)
+  // and which ordinary `sheets` authorization deliberately does not request.
+  // Same invalid_scope caveat as `services`: Google rejects the WHOLE request
+  // if the scope's API is not enabled on the OAuth client's project, and that
+  // happens in the user's browser, so this wrapper cannot catch it.
+  const extraScopesDescribe =
+    'Additional raw OAuth scope URIs to request, comma-separated, on top of the ones `services` implies. ' +
+    'Use for scopes no service covers — 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 ' +
@@ -91,10 +105,19 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     inputSchema: {
       email: z.string().describe('Google account email to authorize'),
       services: z.string().optional().default(defaultServices).describe(servicesDescribe),
+      extraScopes: z.string().optional().describe(extraScopesDescribe),
     },
-  }, async ({ email, services = defaultServices }) => {
+  }, async ({ email, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(['auth', 'add', email, '--services', services], {
+      const args = ['auth', 'add', email, '--services', services];
+      // --force-consent rides along with extraScopes and only with them. Google
+      // re-prompts for a NEW scope only when consent is forced; without it the
+      // account can come back still missing the scope, with a success message —
+      // the exact shape of failure the caller cannot see. The other two tools
+      // force consent unconditionally; this one does not, so it must be added
+      // here rather than assumed.
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`, '--force-consent');
+      return rawTextResult(await run(args, {
         interactive: true,
         timeout: 300_000,
       }));
@@ -115,17 +138,17 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     inputSchema: {
       email: z.string().describe('Google account email to authorize'),
       services: z.string().optional().default(defaultServices).describe(servicesDescribe),
+      extraScopes: z.string().optional().describe(`${extraScopesDescribe} Pass the SAME value to gog_auth_add_complete.`),
     },
-  }, async ({ email, services = defaultServices }) => {
+  }, async ({ email, services = defaultServices, extraScopes }) => {
     try {
       // --force-consent guarantees a refresh token even if a prior grant exists
       // (the whole point when recovering from a dead one). redactMode 'tokens'
       // keeps the consent URL's scope names intact (the shared redactor mangles
       // them) while still stripping any real token — a step-1 URL carries none.
-      return rawTextResult(await run(
-        ['auth', 'add', email, '--remote', '--step', '1', '--services', services, '--force-consent'],
-        { redactMode: 'tokens' },
-      ));
+      const args = ['auth', 'add', email, '--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));
     }
@@ -147,13 +170,17 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
       services: z.string().optional().default(defaultServices).describe(
         `Services authorized — MUST match the value passed to gog_auth_add_url. Default: "${defaultServices}".`,
       ),
+      extraScopes: z.string().optional().describe(
+        'Extra OAuth scope URIs — 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, redirectUrl, services = defaultServices }) => {
+  }, async ({ email, redirectUrl, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(
-        ['auth', 'add', email, '--remote', '--step', '2', '--auth-url', redirectUrl,
-          '--services', services, '--force-consent'],
-      ));
+      const args = ['auth', 'add', email, '--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));
     }

package/src/tools/calendar.ts

@@ -5,15 +5,22 @@ import { annotateTruncatedList } from '../pagination.js';
 
 export function registerCalendarTools(server: McpServer): void {
   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 — never conclude an event does not exist from one.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       calendarId: z.string().optional().describe('Calendar ID (default: primary calendar)'),
       from: z.string().optional().describe('Start time filter (RFC3339, date, or natural language)'),
-      to: z.string().optional().describe('End time filter (RFC3339, date, or natural language)'),
-      today: z.boolean().optional().describe('Only show today\'s events'),
+      to: z.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: z.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: z.boolean().optional().describe('Only show today\'s events. A complete window on its own — mutually exclusive with from, to and days.'),
       query: z.string().optional().describe('Free text search within events'),
       max: z.number().int().optional().describe('Max events to return. gog defaults to 10, which silently hides the rest — raise it, or page with pageToken.'),
       pageToken: pageTokenParam,
@@ -23,11 +30,12 @@ export function registerCalendarTools(server: McpServer): void {
       timezone: z.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, max, pageToken, page, 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 !== undefined) args.push(`--days=${days}`);
     if (today) args.push('--today');
     if (query) args.push(`--query=${query}`);
     if (max !== undefined) args.push(`--max=${max}`);

package/src/tools/gmail.ts

@@ -46,16 +46,22 @@ export function registerGmailTools(server: McpServer): void {
   });
 
   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: z.string().describe('Message ID'),
       format: z.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: z.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 — 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 });
   });
 

package/src/worker.ts

@@ -38,7 +38,7 @@ import { gogAuth, CONNECTOR_INSTRUCTIONS, type GogProps } from './connector-auth
 // connector with all ~360 tools at once. Add whichever paths you want as separate
 // connectors in claude.ai (each authorizes with the same connector key).
 
-const VERSION = '2.23.2'; // x-release-please-version
+const VERSION = '2.24.0'; // x-release-please-version
 
 // Build an McpAgent subclass whose init() registers `registrars` onto its server,
 // each handler wrapped in the ALS scope carrying the per-session Fly executor.

package/tests/tools/auth.test.ts

@@ -124,6 +124,35 @@ describe('gog_auth_add', () => {
     );
   });
 
+  // gog 0.37.0's Connected Sheets reads need bigquery.readonly, which no
+  // `services` selection covers. --force-consent is not optional alongside it:
+  // Google re-prompts for a NEW scope only when consent is forced, so without
+  // it the grant can come back missing the scope AND reporting success.
+  it('passes --extra-scopes with --force-consent', async () => {
+    vi.mocked(runner.run).mockResolvedValue('Authorization successful');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_auth_add', {
+      email: 'user@gmail.com',
+      services: 'sheets',
+      extraScopes: 'https://www.googleapis.com/auth/bigquery.readonly',
+    });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['auth', 'add', 'user@gmail.com', '--services', 'sheets',
+        '--extra-scopes=https://www.googleapis.com/auth/bigquery.readonly', '--force-consent'],
+      { interactive: true, timeout: 300_000 },
+    );
+  });
+
+  it('does not force consent when no extra scopes are asked for', async () => {
+    vi.mocked(runner.run).mockResolvedValue('Authorization successful');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_auth_add', { email: 'user@gmail.com' });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['auth', 'add', 'user@gmail.com', '--services', 'all'],
+      { interactive: true, timeout: 300_000 },
+    );
+  });
+
   it('returns error text on failure', async () => {
     vi.mocked(runner.run).mockRejectedValue(new Error('Auth cancelled by user'));
     const harness = await setupHandlers();
@@ -215,6 +244,21 @@ describe('gog_auth_add_url', () => {
     );
   });
 
+  it('appends --extra-scopes after the service scopes', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"auth_url":"https://x"}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_auth_add_url', {
+      email: 'user@gmail.com',
+      services: 'sheets',
+      extraScopes: 'https://www.googleapis.com/auth/bigquery.readonly',
+    });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['auth', 'add', 'user@gmail.com', '--remote', '--step', '1', '--services', 'sheets', '--force-consent',
+        '--extra-scopes=https://www.googleapis.com/auth/bigquery.readonly'],
+      { redactMode: 'tokens' },
+    );
+  });
+
   it('returns error text on failure', async () => {
     vi.mocked(runner.run).mockRejectedValue(new Error('client not configured'));
     const harness = await setupHandlers();
@@ -252,6 +296,22 @@ describe('gog_auth_add_complete', () => {
     );
   });
 
+  it('carries the same --extra-scopes as step 1', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"stored":true}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_auth_add_complete', {
+      email: 'user@gmail.com',
+      redirectUrl: 'http://127.0.0.1/cb?code=c&state=s',
+      services: 'sheets',
+      extraScopes: 'https://www.googleapis.com/auth/bigquery.readonly',
+    });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['auth', 'add', 'user@gmail.com', '--remote', '--step', '2', '--auth-url',
+        'http://127.0.0.1/cb?code=c&state=s', '--services', 'sheets', '--force-consent',
+        '--extra-scopes=https://www.googleapis.com/auth/bigquery.readonly'],
+    );
+  });
+
   it('returns error text on failure (e.g. expired state)', async () => {
     vi.mocked(runner.run).mockRejectedValue(new Error('no matching manual auth state'));
     const harness = await setupHandlers();

package/tests/tools/calendar.test.ts

@@ -17,23 +17,50 @@ describe('gog_calendar_events', () => {
     expect(runner.run).toHaveBeenCalledWith(['calendar', 'events'], { account: undefined });
   });
 
-  it('appends calendarId and filters when provided', async () => {
+  // The window flags are pinned as SEPARATE cases on purpose: gog >= 0.36.0
+  // (openclaw/gogcli#981) rejects a fixed preset combined with from/to/days,
+  // and days combined with to, so one test passing them all at once would
+  // assert an arg array gog refuses to run.
+  it('appends calendarId and an explicit from/to range', async () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
     await harness.callTool('gog_calendar_events', {
       calendarId: 'primary',
       from: '2026-01-01',
       to: '2026-01-31',
-      today: true,
       query: 'standup',
       all: true,
     });
     expect(runner.run).toHaveBeenCalledWith(
-      ['calendar', 'events', 'primary', '--from=2026-01-01', '--to=2026-01-31', '--today', '--query=standup', '--all'],
+      ['calendar', 'events', 'primary', '--from=2026-01-01', '--to=2026-01-31', '--query=standup', '--all'],
       { account: undefined },
     );
   });
 
+  it('appends --today on its own', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_calendar_events', { today: true });
+    expect(runner.run).toHaveBeenCalledWith(['calendar', 'events', '--today'], { account: undefined });
+  });
+
+  it('anchors --days at --from when both are given', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_calendar_events', { from: '2026-09-25', days: 5 });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['calendar', 'events', '--from=2026-09-25', '--days=5'],
+      { account: undefined },
+    );
+  });
+
+  it('passes --days alone as a today-anchored window', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_calendar_events', { days: 7 });
+    expect(runner.run).toHaveBeenCalledWith(['calendar', 'events', '--days=7'], { account: undefined });
+  });
+
   it('repeats --event-types for each requested type', async () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();

package/tests/tools/gmail.test.ts

@@ -201,6 +201,23 @@ describe('gog_gmail_get', () => {
     expect(runner.run).toHaveBeenCalledWith(['gmail', 'get', 'msg1', '--format=metadata'], { account: undefined });
   });
 
+  // gog >= 0.37.0 (openclaw/gogcli#992): before that release the sanitized
+  // JSON repeated the headers and body at the top level, so this flag grew the
+  // payload it exists to shrink. Pinned here as the flag spelling gog expects.
+  it('appends --sanitize-content when asked', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_gmail_get', { messageId: 'msg1', sanitizeContent: true });
+    expect(runner.run).toHaveBeenCalledWith(['gmail', 'get', 'msg1', '--sanitize-content'], { account: undefined });
+  });
+
+  it('omits --sanitize-content when false', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_gmail_get', { messageId: 'msg1', sanitizeContent: false });
+    expect(runner.run).toHaveBeenCalledWith(['gmail', 'get', 'msg1'], { account: undefined });
+  });
+
   it('returns error text on failure', async () => {
     vi.mocked(runner.run).mockRejectedValue(new Error('Not found'));
     const harness = await setupHandlers();