gogcli-mcp-sheets 4.2.5 → 4.3.0

package/dist/index.js

@@ -2092,8 +2092,8 @@ function emoji() {
 }
 var ipv4 = /^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$/;
 var ipv6 = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$/;
-var mac = (delimiter2) => {
-  const escapedDelim = escapeRegex(delimiter2 ?? ":");
+var mac = (delimiter3) => {
+  const escapedDelim = escapeRegex(delimiter3 ?? ":");
   return new RegExp(`^(?:[0-9A-F]{2}${escapedDelim}){5}[0-9A-F]{2}$|^(?:[0-9a-f]{2}${escapedDelim}){5}[0-9a-f]{2}$`);
 };
 var cidrv4 = /^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\/([0-9]|[1-2][0-9]|3[0-2])$/;
@@ -5121,7 +5121,7 @@ var recursive = /* @__PURE__ */ new WeakMap();
 var NONE = 0;
 var ASSUMED = 1;
 var PROVEN = 2;
-function isRecursive(inst, stack, resolve) {
+function isRecursive(inst, stack, resolve4) {
   const cached2 = recursive.get(inst);
   if (cached2 !== void 0)
     return cached2 ? PROVEN : NONE;
@@ -5131,7 +5131,7 @@ function isRecursive(inst, stack, resolve) {
   let result = NONE;
   const check2 = (child) => {
     if (result !== PROVEN && child?._zod) {
-      const answer = isRecursive(child, stack, resolve);
+      const answer = isRecursive(child, stack, resolve4);
       if (answer > result)
         result = answer;
     }
@@ -5142,7 +5142,7 @@ function isRecursive(inst, stack, resolve) {
       const desc = Object.getOwnPropertyDescriptor(sh, key);
       if (spread && !desc.enumerable)
         continue;
-      const child = desc.get ? ASSUMED : desc.value?._zod ? isRecursive(desc.value, stack, resolve) : NONE;
+      const child = desc.get ? ASSUMED : desc.value?._zod ? isRecursive(desc.value, stack, resolve4) : NONE;
       if (child > answer)
         answer = child;
     }
@@ -5206,7 +5206,7 @@ function isRecursive(inst, stack, resolve) {
       break;
     // `$ZodLazy` caches its inner on the def, so a resolved edge is followed exactly
     case "lazy": {
-      const inner = def._cachedInner ?? (resolve ? inst._zod.innerType : void 0);
+      const inner = def._cachedInner ?? (resolve4 ? inst._zod.innerType : void 0);
       merge2(inner ? isRecursive(inner, stack, false) : ASSUMED);
       break;
     }
@@ -24106,14 +24106,14 @@ function inputRequiredRoundsExceededMessage(method, maxRounds) {
   return `Multi-round-trip request '${method}' still required input after ${maxRounds} rounds (inputRequired.maxRounds)`;
 }
 function sleep(ms, signal) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve4, reject) => {
     if (signal?.aborted) {
       reject(signal.reason instanceof SdkError ? signal.reason : new SdkError(SdkErrorCode.RequestTimeout, String(signal.reason)));
       return;
     }
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve();
+      resolve4();
     }, ms);
     const onAbort = () => {
       clearTimeout(timer);
@@ -24907,7 +24907,7 @@ var Protocol = class {
     const flowStartedAt = Date.now();
     let onAbort;
     let cleanupMessageId;
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve4, reject) => {
       const earlyReject = (error62) => {
         reject(error62);
       };
@@ -24975,7 +24975,7 @@ var Protocol = class {
         }
         if (decoded.kind === "invalid") return reject(decoded.error);
         if (decoded.kind === "input_required") {
-          if (options?.allowInputRequired === true) return resolve(manualInputRequiredValue(decoded));
+          if (options?.allowInputRequired === true) return resolve4(manualInputRequiredValue(decoded));
           const flow = {
             codec: codec2,
             request,
@@ -24987,11 +24987,11 @@ var Protocol = class {
               params
             }, resultSchema, legOptions)
           };
-          return resolve(this._resolveNonCompleteResult(decoded, flow));
+          return resolve4(this._resolveNonCompleteResult(decoded, flow));
         }
         const result = decoded.result;
         validateStandardSchema(resultSchema, result).then((parseResult) => {
-          if (parseResult.success) resolve(parseResult.data);
+          if (parseResult.success) resolve4(parseResult.data);
           else reject(new SdkError(SdkErrorCode.InvalidResult, `Invalid result for ${request.method}: ${parseResult.error}`));
         }, reject);
       });
@@ -27903,7 +27903,7 @@ var require_compile = /* @__PURE__ */ __commonJSMin(((exports) => {
     ref = (0, resolve_1.resolveUrl)(this.opts.uriResolver, baseId, ref);
     const schOrFunc = root.refs[ref];
     if (schOrFunc) return schOrFunc;
-    let _sch = resolve.call(this, root, ref);
+    let _sch = resolve4.call(this, root, ref);
     if (_sch === void 0) {
       const schema = (_a3 = root.localRefs) === null || _a3 === void 0 ? void 0 : _a3[ref];
       const { schemaId } = this.opts;
@@ -27929,7 +27929,7 @@ var require_compile = /* @__PURE__ */ __commonJSMin(((exports) => {
   function sameSchemaEnv(s1, s2) {
     return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
   }
-  function resolve(root, ref) {
+  function resolve4(root, ref) {
     let sch;
     while (typeof (sch = this.refs[ref]) == "string") ref = sch;
     return sch || this.schemas[ref] || resolveSchema.call(this, root, ref);
@@ -28379,47 +28379,47 @@ var require_fast_uri = /* @__PURE__ */ __commonJSMin(((exports, module) => {
     else if (typeof uri === "object") uri = parse3(serialize(uri, options), options);
     return uri;
   }
-  function resolve(baseURI, relativeURI, options) {
+  function resolve4(baseURI, relativeURI, options) {
     const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
     const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
     schemelessOptions.skipEscape = true;
     return serialize(resolved, schemelessOptions);
   }
-  function resolveComponent(base, relative, options, skipNormalization) {
+  function resolveComponent(base, relative3, options, skipNormalization) {
     const target = {};
     if (!skipNormalization) {
       base = parse3(serialize(base, options), options);
-      relative = parse3(serialize(relative, options), options);
+      relative3 = parse3(serialize(relative3, options), options);
     }
     options = options || {};
-    if (!options.tolerant && relative.scheme) {
-      target.scheme = relative.scheme;
-      target.userinfo = relative.userinfo;
-      target.host = relative.host;
-      target.port = relative.port;
-      target.path = removeDotSegments(relative.path || "");
-      target.query = relative.query;
+    if (!options.tolerant && relative3.scheme) {
+      target.scheme = relative3.scheme;
+      target.userinfo = relative3.userinfo;
+      target.host = relative3.host;
+      target.port = relative3.port;
+      target.path = removeDotSegments(relative3.path || "");
+      target.query = relative3.query;
     } else {
-      if (relative.userinfo !== void 0 || relative.host !== void 0 || relative.port !== void 0) {
-        target.userinfo = relative.userinfo;
-        target.host = relative.host;
-        target.port = relative.port;
-        target.path = removeDotSegments(relative.path || "");
-        target.query = relative.query;
+      if (relative3.userinfo !== void 0 || relative3.host !== void 0 || relative3.port !== void 0) {
+        target.userinfo = relative3.userinfo;
+        target.host = relative3.host;
+        target.port = relative3.port;
+        target.path = removeDotSegments(relative3.path || "");
+        target.query = relative3.query;
       } else {
-        if (!relative.path) {
+        if (!relative3.path) {
           target.path = base.path;
-          if (relative.query !== void 0) target.query = relative.query;
+          if (relative3.query !== void 0) target.query = relative3.query;
           else target.query = base.query;
         } else {
-          if (relative.path[0] === "/") target.path = removeDotSegments(relative.path);
+          if (relative3.path[0] === "/") target.path = removeDotSegments(relative3.path);
           else {
-            if ((base.userinfo !== void 0 || base.host !== void 0 || base.port !== void 0) && !base.path) target.path = "/" + relative.path;
-            else if (!base.path) target.path = relative.path;
-            else target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative.path;
+            if ((base.userinfo !== void 0 || base.host !== void 0 || base.port !== void 0) && !base.path) target.path = "/" + relative3.path;
+            else if (!base.path) target.path = relative3.path;
+            else target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative3.path;
             target.path = removeDotSegments(target.path);
           }
-          target.query = relative.query;
+          target.query = relative3.query;
         }
         target.userinfo = base.userinfo;
         target.host = base.host;
@@ -28427,7 +28427,7 @@ var require_fast_uri = /* @__PURE__ */ __commonJSMin(((exports, module) => {
       }
       target.scheme = base.scheme;
     }
-    target.fragment = relative.fragment;
+    target.fragment = relative3.fragment;
     return target;
   }
   function equal(uriA, uriB, options) {
@@ -28553,7 +28553,7 @@ var require_fast_uri = /* @__PURE__ */ __commonJSMin(((exports, module) => {
   const fastUri = {
     SCHEMES,
     normalize,
-    resolve,
+    resolve: resolve4,
     resolveComponent,
     equal,
     serialize,
@@ -29335,14 +29335,14 @@ var require_ucs2length = /* @__PURE__ */ __commonJSMin(((exports) => {
   function ucs2length(str) {
     const len = str.length;
     let length = 0;
-    let pos = 0;
+    let pos2 = 0;
     let value;
-    while (pos < len) {
+    while (pos2 < len) {
       length++;
-      value = str.charCodeAt(pos++);
-      if (value >= 55296 && value <= 56319 && pos < len) {
-        value = str.charCodeAt(pos);
-        if ((value & 64512) === 56320) pos++;
+      value = str.charCodeAt(pos2++);
+      if (value >= 55296 && value <= 56319 && pos2 < len) {
+        value = str.charCodeAt(pos2);
+        if ((value & 64512) === 56320) pos2++;
       }
     }
     return length;
@@ -33926,7 +33926,7 @@ var StdioServerTransport = class {
   }
   send(message) {
     if (this._closed) return Promise.reject(/* @__PURE__ */ new Error("StdioServerTransport is closed"));
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve4, reject) => {
       const json2 = serializeMessage(message);
       let settled = false;
       const onError = (error62) => {
@@ -33941,14 +33941,14 @@ var StdioServerTransport = class {
         settled = true;
         this._stdout.off("error", onError);
         this._stdout.off("drain", onDrain);
-        resolve();
+        resolve4();
       };
       this._stdout.once("error", onError);
       if (this._stdout.write(json2)) {
         if (settled) return;
         settled = true;
         this._stdout.off("error", onError);
-        resolve();
+        resolve4();
       } else if (!settled) this._stdout.once("drain", onDrain);
     });
   }
@@ -34002,14 +34002,14 @@ var StdioConnectionChannel = class {
   */
   async whenRequestsAnswered(timeoutMs) {
     if (this._closed || this._pendingRequests.size === 0) return true;
-    return await new Promise((resolve) => {
+    return await new Promise((resolve4) => {
       const waiter = () => {
         clearTimeout(timer);
-        resolve(true);
+        resolve4(true);
       };
       const timer = setTimeout(() => {
         this._drainWaiters = this._drainWaiters.filter((pending) => pending !== waiter);
-        resolve(false);
+        resolve4(false);
       }, timeoutMs);
       this._drainWaiters.push(waiter);
     });
@@ -34379,13 +34379,28 @@ var API_KEY_RE = new RegExp([
   "whsec_[A-Za-z0-9]{16,}\\b"
   // webhook signing secret (Stripe-style)
 ].map((p) => `\\b${p}`).join("|"), "g");
-var QUERY_SECRET_RE = /([?&](?:access_token|refresh_token|client_secret|api_?key|signature|token|key|sig)=)[^&#\s"'<>`]+/gi;
+var QUERY_SECRET_RE = /([?&](?:(?:access|refresh|id|auth|session|csrf|xsrf)[_-]?token|client[_-]?secret|api[_-]?secret|api[_-]?key|password|passwd|signature|token|key|sig)=)[^&#\s"'<>`]+/gi;
+var OAUTH_CODE_RE = /([?&]code=)(?=[^&#\s"'<>`]{16,})[^&#\s"'<>`]+/gi;
+var FORM_PASSWORD_RE = /((?:^|[\s,;:"'(\[{])(?:password|passwd)=)[^&#\s"'<>`]+/gim;
+var HEADER_SECRET_RE = /(\b(?:x[-_][a-z0-9_-]*?(?:api[-_]?key|token|secret|auth)[a-z0-9_-]*|api[-_]?key)\s*:\s*)[^\s,;"'<>`]+/gi;
 var AWS_SIGV4_RE = /([?&]X-Amz-(?:Signature|Security-Token|Credential)=)[^&#\s"'<>`]+/gi;
-var JSON_SECRET_KEYS = "access_token|refresh_token|client_secret|api_?key|password|passwd|secret|token";
-var JSON_SECRET_DQ_RE = new RegExp(`("(?:${JSON_SECRET_KEYS})"\\s*:\\s*")[^"]*(")`, "gi");
-var JSON_SECRET_SQ_RE = new RegExp(`('(?:${JSON_SECRET_KEYS})'\\s*:\\s*')[^']*(')`, "gi");
+var JSON_SECRET_KEYS = [
+  "(?:access|refresh|id|auth|session|bearer|csrf|xsrf)[_-]?token",
+  "client[_-]?secret",
+  "api[_-]?secret",
+  "(?:x[_-])?api[_-]?key",
+  "private[_-]?key",
+  "x[_-][a-z0-9_-]*?(?:api[_-]?key|token|secret|auth)[a-z0-9_-]*",
+  "(?:proxy-)?authorization",
+  "password",
+  "passwd",
+  "secret",
+  "token"
+].join("|");
+var JSON_SECRET_DQ_RE = new RegExp(`("(?:${JSON_SECRET_KEYS})"\\s*:\\s*")(?:[^"\\\\]|\\\\.)*(")`, "gi");
+var JSON_SECRET_SQ_RE = new RegExp(`('(?:${JSON_SECRET_KEYS})'\\s*:\\s*')(?:[^'\\\\]|\\\\.)*(')`, "gi");
 function redactSecrets(text) {
-  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JWT_RE, "[REDACTED]");
+  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(HEADER_SECRET_RE, "$1[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(OAUTH_CODE_RE, "$1[REDACTED]").replace(FORM_PASSWORD_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JWT_RE, "[REDACTED]");
 }
 
 // ../../node_modules/@chrischall/mcp-utils/dist/response/view.js
@@ -34547,13 +34562,47 @@ async function createMcpServer(opts) {
   }
   return server;
 }
+var DEFAULT_SHUTDOWN_TIMEOUT_MS = 5e3;
+var DEFAULT_REPEAT_SIGNAL_GRACE_MS = 500;
 function withGracefulShutdown(target, opts = {}) {
   const shouldExit = opts.exit ?? true;
+  if (opts.timeoutMs !== void 0 && !(Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0)) {
+    throw new RangeError("withGracefulShutdown: timeoutMs must be a finite number greater than 0.");
+  }
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+  if (opts.repeatSignalGraceMs !== void 0 && !(Number.isFinite(opts.repeatSignalGraceMs) && opts.repeatSignalGraceMs >= 0)) {
+    throw new RangeError("withGracefulShutdown: repeatSignalGraceMs must be a finite number >= 0.");
+  }
+  const repeatGraceMs = opts.repeatSignalGraceMs ?? DEFAULT_REPEAT_SIGNAL_GRACE_MS;
   let shuttingDown = false;
+  let firstSignalAt = 0;
+  let exited = false;
+  const exitOnce = () => {
+    if (exited)
+      return;
+    exited = true;
+    process.exit(0);
+  };
   const handler = (signal) => {
-    if (shuttingDown)
+    if (shuttingDown) {
+      if (Date.now() - firstSignalAt < repeatGraceMs)
+        return;
+      if (shouldExit) {
+        console.error(`[mcp-utils] second ${signal} during shutdown \u2014 exiting now`);
+        exitOnce();
+      }
       return;
+    }
     shuttingDown = true;
+    firstSignalAt = Date.now();
+    let timer;
+    if (shouldExit) {
+      timer = setTimeout(() => {
+        console.error(`[mcp-utils] graceful shutdown on ${signal} did not finish in ${timeoutMs}ms \u2014 exiting`);
+        exitOnce();
+      }, timeoutMs);
+      timer.unref?.();
+    }
     void (async () => {
       try {
         if (opts.onSignal)
@@ -34562,8 +34611,10 @@ function withGracefulShutdown(target, opts = {}) {
       } catch (err) {
         console.error(`[mcp-utils] error during graceful shutdown on ${signal}: ${err instanceof Error ? err.message : String(err)}`);
       } finally {
+        if (timer !== void 0)
+          clearTimeout(timer);
         if (shouldExit)
-          process.exit(0);
+          exitOnce();
       }
     })();
   };
@@ -34593,6 +34644,8 @@ function runMcp(opts) {
 }
 
 // ../../node_modules/@chrischall/mcp-utils/dist/config/index.js
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
 var PLACEHOLDER_RE = /^\$\{[^}]*\}$/;
 function readEnvVar(key, opts = {}) {
   const env = opts.env ?? process.env;
@@ -34619,6 +34672,50 @@ function parseBoolEnv(key, opts = {}) {
     return false;
   return fallback;
 }
+function expandPath(p) {
+  let expanded = p;
+  if (p === "~") {
+    expanded = homedir();
+  } else if (p.startsWith("~/")) {
+    expanded = join(homedir(), p.slice(2));
+  }
+  return isAbsolute(expanded) ? expanded : resolve(expanded);
+}
+
+// ../../node_modules/@chrischall/mcp-utils/dist/fs/confine.js
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute as isAbsolute2, relative, resolve as resolve2, sep } from "node:path";
+function isInside(root, target) {
+  const rel = relative(root, target);
+  return rel === "" || !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute2(rel);
+}
+function realPathAllowingMissing(p) {
+  const abs = resolve2(p);
+  let existing = abs;
+  const tail = [];
+  while (!existsSync(existing)) {
+    const parent = dirname(existing);
+    if (parent === existing)
+      break;
+    tail.unshift(existing.slice(parent.length).replace(/^[/\\]+/, ""));
+    existing = parent;
+  }
+  let real;
+  try {
+    real = realpathSync(existing);
+  } catch {
+    real = existing;
+  }
+  return tail.length > 0 ? resolve2(real, ...tail) : real;
+}
+function assertPathWithinRoots(path, roots) {
+  const target = realPathAllowingMissing(expandPath(path));
+  for (const root of roots) {
+    if (isInside(realPathAllowingMissing(expandPath(root)), target))
+      return target;
+  }
+  throw new Error(`Path is outside the allowed directories: ${path}`);
+}
 
 // ../../node_modules/@chrischall/mcp-utils/dist/zod/index.js
 var PositiveInt = external_exports.number().int().positive();
@@ -34640,7 +34737,7 @@ var pageSchema = {
 };
 
 // ../gogcli-mcp/src/runner.ts
-import { delimiter, join } from "node:path";
+import { delimiter, join as join2 } from "node:path";
 
 // ../gogcli-mcp/src/timestamps.ts
 var DEFAULT_DISPLAY_TZ = "America/New_York";
@@ -34841,9 +34938,48 @@ function normalizeTimestamps(text, tz = displayTimeZone(), naiveTz = naiveSource
   return JSON.stringify(parsed, null, detectIndent(text));
 }
 
+// ../gogcli-mcp/src/arg-guard.ts
+var 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;
+var SHORT_ACCOUNT_CLUSTER = /^-(?!-)[A-Za-z]*a/;
+function forbiddenArgReason(arg) {
+  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 void 0;
+}
+function assertSafeForwardedArgs(args) {
+  for (const arg of args) {
+    const reason = forbiddenArgReason(arg);
+    if (reason) throw new Error(reason);
+  }
+}
+var SUBCOMMAND_SHAPE = /^[a-z][a-z0-9-]*$/;
+function assertSafeSubcommand(subcommand) {
+  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.`
+    );
+  }
+}
+
+// ../gogcli-mcp/src/argv.ts
+function pos(value) {
+  return { kind: "positional", value };
+}
+function isGogPositional(arg) {
+  return typeof arg === "object" && arg !== null && arg.kind === "positional";
+}
+
 // ../gogcli-mcp/src/runner.ts
 function isGogFileArg(arg) {
-  return typeof arg !== "string";
+  return typeof arg !== "string" && arg.kind === "file";
 }
 var TIMEOUT_MS = 3e4;
 function readonlyEnvEnabled() {
@@ -34927,8 +35063,8 @@ function formatTimeout(ms) {
 }
 async function spawnWithTempFiles(args, opts) {
   const { mkdtemp, mkdir, writeFile, rm } = await import("node:fs/promises");
-  const { tmpdir } = await import("node:os");
-  const dir = await mkdtemp(join(tmpdir(), "gogcli-mcp-"));
+  const { tmpdir: tmpdir2 } = await import("node:os");
+  const dir = await mkdtemp(join2(tmpdir2(), "gogcli-mcp-"));
   try {
     const argv = [];
     let seq = 0;
@@ -34937,10 +35073,10 @@ async function spawnWithTempFiles(args, opts) {
         argv.push(arg);
         continue;
       }
-      const sub = join(dir, String(seq));
+      const sub = join2(dir, String(seq));
       seq += 1;
       await mkdir(sub, { recursive: true, mode: 448 });
-      const path = join(sub, arg.filename ?? `${arg.flag}.${arg.ext ?? "txt"}`);
+      const path = join2(sub, arg.filename ?? `${arg.flag}.${arg.ext ?? "txt"}`);
       const data = arg.encoding === "base64" ? Buffer.from(arg.contents, "base64") : Buffer.from(arg.contents, "utf8");
       await writeFile(path, data, { mode: 384 });
       argv.push(arg.positional ? path : `--${arg.flag}=${path}`);
@@ -34958,10 +35094,10 @@ function spawnExecutor(args, opts) {
   return spawnGog(args, opts);
 }
 async function spawnGog(fullArgs, opts) {
-  const { timeout, interactive = false, spawner, binary = false } = opts;
+  const { timeout, interactive = false, spawner, binary = false, maxOutputBytes } = opts;
   const spawn = spawner ?? (await import("node:child_process")).spawn;
   const effectiveTimeout = timeout ?? TIMEOUT_MS;
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve4, reject) => {
     const childEnv = { ...sanitizedEnv(), GOG_TIMEZONE: naiveSourceTimeZone(), PATH: augmentedPath() };
     const child = spawn(readEnvVar("GOG_PATH") ?? "gog", fullArgs, { env: childEnv });
     const stdoutChunks = [];
@@ -34979,7 +35115,17 @@ async function spawnGog(fullArgs, opts) {
       child.kill();
       reject(new Error(`gog timed out after ${formatTimeout(effectiveTimeout)}`));
     }, effectiveTimeout);
+    let stdoutBytes = 0;
     child.stdout.on("data", (chunk) => {
+      if (settled) return;
+      stdoutBytes += chunk.length;
+      if (maxOutputBytes !== void 0 && stdoutBytes > maxOutputBytes) {
+        settled = true;
+        stopWatching();
+        child.kill();
+        reject(new Error(`gog output exceeded the limit: more than ${maxOutputBytes} bytes`));
+        return;
+      }
       stdoutChunks.push(chunk);
     });
     child.stderr.on("data", (chunk) => {
@@ -34996,14 +35142,14 @@ async function spawnGog(fullArgs, opts) {
       const stderr = Buffer.concat(stderrChunks).toString().trim();
       if (code === 0) {
         if (binary) {
-          resolve(Buffer.concat(stdoutChunks).toString("base64"));
+          resolve4(Buffer.concat(stdoutChunks).toString("base64"));
           return;
         }
         const stdout = Buffer.concat(stdoutChunks).toString();
         if (interactive && stderr) {
-          resolve(stdout + "\n" + stderr);
+          resolve4(stdout + "\n" + stderr);
         } else {
-          resolve(stdout);
+          resolve4(stdout);
         }
       } else {
         reject(new Error(stderr || `gog exited with code ${code}`));
@@ -35023,7 +35169,33 @@ async function spawnGog(fullArgs, opts) {
     });
   });
 }
+function placePositionals(args) {
+  const flags = [];
+  const positionals = [];
+  let afterSeparator = false;
+  for (const arg of args) {
+    if (arg === "--") {
+      afterSeparator = true;
+    } else if (isGogPositional(arg)) {
+      positionals.push(arg.value);
+    } else if (afterSeparator || isGogFileArg(arg) && arg.positional) {
+      positionals.push(arg);
+    } else {
+      flags.push(arg);
+    }
+  }
+  return { flags, positionals };
+}
+function assertNoSafetyOverrides(flags) {
+  for (const arg of flags) {
+    if (typeof arg !== "string") continue;
+    const reason = forbiddenArgReason(arg);
+    if (reason) throw new Error(reason);
+  }
+}
 function assembleArgs(args, opts) {
+  const { flags, positionals } = placePositionals(args);
+  assertNoSafetyOverrides(flags);
   const effectiveAccount = opts.account ?? readEnvVar("GOG_ACCOUNT");
   const fullArgs = ["--json", "--color=never"];
   if (!opts.interactive) {
@@ -35032,17 +35204,21 @@ function assembleArgs(args, opts) {
   if (opts.readonly || readonlyEnvEnabled()) {
     fullArgs.push("--readonly");
   }
+  if (opts.gmailNoSend) {
+    fullArgs.push("--gmail-no-send");
+  }
   if (effectiveAccount) {
     fullArgs.push("--account", effectiveAccount);
   }
-  fullArgs.push(...args);
+  fullArgs.push(...flags);
+  if (positionals.length > 0) fullArgs.push("--", ...positionals);
   return fullArgs;
 }
 async function run(args, options = {}) {
-  const { account, spawner, interactive = false, timeout, readonly: readonly2 = false, redactMode = "full", opaqueFields } = options;
+  const { account, spawner, interactive = false, timeout, readonly: readonly2 = false, redactMode = "full", opaqueFields, gmailNoSend = false } = options;
   const base = redactMode === "tokens" ? redactGoogleTokens : redactSecrets2;
   const redact = opaqueFields?.length ? (text) => redactPreservingOpaqueFields(text, opaqueFields, base) : base;
-  const fullArgs = assembleArgs(args, { account, interactive, readonly: readonly2 });
+  const fullArgs = assembleArgs(args, { account, interactive, readonly: readonly2, gmailNoSend });
   try {
     return redact(await spawnExecutor(fullArgs, { timeout, interactive, spawner }));
   } catch (err) {
@@ -35070,6 +35246,111 @@ function stripConsumedPageToken(text) {
   return JSON.stringify(obj, null, detectIndent2(text));
 }
 
+// ../gogcli-mcp/src/file-roots.ts
+import { homedir as homedir2 } from "node:os";
+import { delimiter as delimiter2, join as join4 } from "node:path";
+
+// ../gogcli-mcp/src/attachment-root.ts
+import { tmpdir, userInfo } from "node:os";
+import { dirname as dirname2, join as join3, relative as relative2, resolve as resolve3, isAbsolute as isAbsolute3, sep as sep2 } from "node:path";
+var ATTACHMENT_DOWNLOAD_ROOT = join3(tmpdir(), `gogcli-mcp-attachments-${userInfo().uid}`);
+var ATTACHMENT_TTL_MS = 24 * 60 * 60 * 1e3;
+
+// ../gogcli-mcp/src/file-roots.ts
+var FILE_ROOTS_ENV = "GOG_FILE_ROOTS";
+function defaultFileRoot() {
+  return join4(homedir2(), "gogcli-mcp-files");
+}
+function fileRoots() {
+  const raw = readEnvVar(FILE_ROOTS_ENV);
+  const roots = (raw ?? "").split(delimiter2).map((r) => r.trim()).filter(Boolean);
+  return roots.length > 0 ? roots : [defaultFileRoot()];
+}
+function confinePath(path, param, opts = {}) {
+  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;
+}
+function confineAtFile(value, param) {
+  if (value.startsWith("@")) confinePath(value.slice(1), param);
+  return value;
+}
+
+// ../gogcli-mcp/src/run-path-guard.ts
+var POSITIONAL_PATH_SUBCOMMANDS = {
+  appscript: { pull: "gog_appscript_pull" },
+  drive: { upload: "gog_drive_upload", sync: "gog_drive_sync_push" },
+  gmail: { import: "gog_gmail_import" },
+  slides: {
+    "add-slide": "gog_slides_add_slide",
+    "insert-image": "gog_slides_insert_image",
+    "replace-slide": "gog_slides_replace_slide"
+  }
+};
+var PATH_FLAGS = /* @__PURE__ */ new Set(["out", "output", "out-dir", "output-dir", "dir", "worker-dir", "attach", "file", "key", "cert", "replacements"]);
+var ID_FLAGS = {
+  drive: /* @__PURE__ */ new Set(["file", "filter-file"])
+};
+var EXEC_FLAGS = /* @__PURE__ */ new Set(["on-change", "on-new", "mmdc"]);
+var SHORT_PATH_CLUSTER = /^-(?!-)[A-Za-z]*[of]/;
+var LONG_FLAG = /^--([A-Za-z0-9][A-Za-z0-9-]*)(?:=([\s\S]*))?$/;
+function isPathFlag(service, name) {
+  if (ID_FLAGS[service]?.has(name)) return false;
+  return PATH_FLAGS.has(name) || name.endsWith("-file");
+}
+function confineFlagValue(flag, value) {
+  if (value === "-") return;
+  confinePath(value, flag);
+  for (const part of value.split(",")) {
+    if (part !== "" && part !== "-") confinePath(part, flag);
+  }
+}
+function positionalPathTool(service, subcommand) {
+  return POSITIONAL_PATH_SUBCOMMANDS[service]?.[subcommand];
+}
+function assertRunPathsConfined(service, subcommand, args) {
+  const dedicated = positionalPathTool(service, subcommand);
+  if (dedicated) {
+    throw new Error(
+      `gog ${service} ${subcommand} reads or writes a local path given as a positional argument, so it is not available through gog_${service}_run. Use ${dedicated}, which confines the path to GOG_FILE_ROOTS.`
+    );
+  }
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (SHORT_PATH_CLUSTER.test(arg)) {
+      throw new Error(
+        `The flag ${arg} is not allowed here: spell a path flag out as --out or --file (e.g. --out=<path>) so its path can be checked against GOG_FILE_ROOTS.`
+      );
+    }
+    const match = LONG_FLAG.exec(arg);
+    if (!match) continue;
+    const name = match[1].toLowerCase();
+    if (EXEC_FLAGS.has(name)) {
+      throw new Error(`The flag --${name} is not allowed here: it runs a local program chosen by the caller.`);
+    }
+    const isJson = name.endsWith("-json");
+    if (!isJson && !isPathFlag(service, name)) continue;
+    let value = match[2];
+    if (value === void 0) {
+      value = args[i + 1];
+      if (value === void 0) continue;
+      i++;
+    }
+    if (isJson) {
+      if (value.startsWith("@")) confineFlagValue(`--${name}`, value.slice(1));
+      continue;
+    }
+    confineFlagValue(`--${name}`, value);
+  }
+}
+
 // ../gogcli-mcp/src/tools/utils.ts
 var PAYLOAD_INLINE_MAX = 4096;
 function payloadArg(inlineFlag, fileFlag, value, ext) {
@@ -35118,9 +35399,17 @@ var paginationParams = {
   all: external_exports.boolean().optional().describe("Fetch all pages")
 };
 function registerRunTool(server, options) {
-  const { service, examples, omitAccount = false, note } = options;
+  const { service, examples, omitAccount = false, note, allowedSubcommands, vet, gmailNoSend = false } = options;
+  for (const [, example] of examples.matchAll(/"([^"]+)"/g)) {
+    const refused = allowedSubcommands && !allowedSubcommands.includes(example) || vet?.(example, []) || positionalPathTool(service, example);
+    if (refused) {
+      throw new Error(`gog_${service}_run example "${example}" is refused by the tool itself; list a subcommand it runs.`);
+    }
+  }
   const baseDescription = `Run any gog ${service} subcommand not covered by the other tools. Run \`gog ${service} --help\` for the full list of subcommands, or \`gog ${service} <subcommand> --help\` for flags on a specific subcommand.`;
-  const description = note ? `${baseDescription} ${note}` : baseDescription;
+  const restriction = allowedSubcommands ? ` Only these subcommands are available: ${allowedSubcommands.join(", ")}.` : "";
+  const safety = ' Flags that override server safety controls (--readonly, --enable-commands, --disable-commands, --account, --access-token, --home, --client, --gmail-no-send, --no-input) and a bare "--" are refused. Local file paths (--out, --out-dir, --attach, --file, --*-file, @file JSON) must be inside GOG_FILE_ROOTS; subcommands that take a local path positionally (e.g. drive upload) are refused in favour of their dedicated tools.';
+  const description = `${baseDescription}${restriction}${safety}${note ? ` ${note}` : ""}`;
   const inputSchema = {
     subcommand: external_exports.string().describe(`The gog ${service} subcommand to run, e.g. ${examples}`),
     args: external_exports.array(external_exports.string()).describe("Additional positional args and flags")
@@ -35134,7 +35423,21 @@ function registerRunTool(server, options) {
     inputSchema: external_exports.object(inputSchema)
   }, async (rawArgs) => {
     const { subcommand, args, account } = rawArgs;
-    return runOrDiagnose([service, subcommand, ...args], { account });
+    try {
+      assertSafeSubcommand(subcommand);
+      assertSafeForwardedArgs(args);
+      if (allowedSubcommands && !allowedSubcommands.includes(subcommand)) {
+        throw new Error(
+          `gog ${service} ${subcommand} is not available through gog_${service}_run. Allowed: ${allowedSubcommands.join(", ")}.`
+        );
+      }
+      const refusal = vet?.(subcommand, args);
+      if (refusal) throw new Error(refusal);
+      assertRunPathsConfined(service, subcommand, args);
+    } catch (err) {
+      return errorResult(errorText(err));
+    }
+    return runOrDiagnose([service, subcommand, ...args], gmailNoSend ? { account, gmailNoSend } : { account });
   });
 }
 function errorText(err) {
@@ -35256,6 +35559,7 @@ function formatAuthHealth(raw, now) {
 }
 
 // ../gogcli-mcp/src/tools/auth.ts
+var AUTH_RUN_SUBCOMMANDS = ["list", "status", "services", "remove", "alias"];
 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.";
@@ -35313,7 +35617,7 @@ function registerAuthToolsWith(server, defaultServices) {
     })
   }, async ({ email: email3, services = defaultServices, extraScopes }) => {
     try {
-      const args = ["auth", "add", email3, "--services", services];
+      const args = ["auth", "add", pos(email3), "--services", services];
       if (extraScopes) args.push(`--extra-scopes=${extraScopes}`, "--force-consent");
       return rawTextResult(await run(args, {
         interactive: true,
@@ -35333,7 +35637,7 @@ function registerAuthToolsWith(server, defaultServices) {
     })
   }, async ({ email: email3, services = defaultServices, extraScopes }) => {
     try {
-      const args = ["auth", "add", email3, "--remote", "--step", "1", "--services", services, "--force-consent"];
+      const args = ["auth", "add", pos(email3), "--remote", "--step", "1", "--services", services, "--force-consent"];
       if (extraScopes) args.push(`--extra-scopes=${extraScopes}`);
       return rawTextResult(await run(args, { redactMode: "tokens" }));
     } catch (err) {
@@ -35360,7 +35664,7 @@ function registerAuthToolsWith(server, defaultServices) {
       const args = [
         "auth",
         "add",
-        email3,
+        pos(email3),
         "--remote",
         "--step",
         "2",
@@ -35380,6 +35684,7 @@ function registerAuthToolsWith(server, defaultServices) {
     service: "auth",
     examples: '"remove", "alias", "list"',
     omitAccount: true,
+    allowedSubcommands: AUTH_RUN_SUBCOMMANDS,
     note: "For browser-based authorization, use gog_auth_add instead."
   });
 }
@@ -35429,7 +35734,7 @@ var replySchema = {
   remove: external_exports.array(external_exports.string()).optional().describe("Remove these recipients from all fields (repeatable) \u2014 e.g. to drop someone from a reply-all."),
   subject: external_exports.string().optional().describe('Override reply subject (default: "Re: <original>"). A changed subject starts a NEW Gmail thread.'),
   noQuote: external_exports.boolean().optional().describe("Do not include the original message quoted below the reply (default: the original is quoted)"),
-  attach: external_exports.array(external_exports.string()).optional().describe(`File paths to attach (repeatable), resolved ON THE GOG SERVER's filesystem \u2014 NOT this client's. Only usable when gog runs on the same machine you do (local stdio); on a hosted deployment (e.g. mcp-host) these paths do not exist and the call fails with "no such file or directory" \u2014 use attachInline there. Read on the server, base64-encoded with a MIME type inferred from the extension.`),
+  attach: external_exports.array(external_exports.string()).optional().describe(`File paths to attach (repeatable), resolved ON THE GOG SERVER's filesystem \u2014 NOT this client's. Only usable when gog runs on the same machine you do (local stdio); on a hosted deployment (e.g. mcp-host) these paths do not exist and the call fails with "no such file or directory" \u2014 use attachInline there. Read on the server, base64-encoded with a MIME type inferred from the extension. Must be inside the server's GOG_FILE_ROOTS directories (default ~/gogcli-mcp-files).`),
   attachInline: attachInlineParam,
   from: external_exports.string().optional().describe("Send from this email address (must be a verified send-as alias)"),
   autoFromAddressedAlias: external_exports.boolean().optional().describe("When from is omitted, send from the verified send-as alias the original message was addressed TO, instead of the account's primary address \u2014 so a reply to mail sent to an alias goes back out from that alias. Ignored when from is set."),
@@ -35506,7 +35811,7 @@ function registerSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, range, account }) => {
-    return runOrDiagnose(["sheets", "get", spreadsheetId, range], { account });
+    return runOrDiagnose(["sheets", "get", pos(spreadsheetId), pos(range)], { account });
   });
   server.registerTool("gog_sheets_update", {
     description: 'Write values to a Google Sheets range, overwriting existing content. Values may be strings, numbers, booleans, or null. Strings starting with "=" are interpreted as formulas (e.g. "=SUM(A1:A10)").',
@@ -35526,7 +35831,7 @@ function registerSheetsTools(server) {
       const readRange = expandAnchorRange(range, values.length, cols);
       let existing;
       try {
-        existing = await run(["sheets", "get", spreadsheetId, readRange], { account });
+        existing = await run(["sheets", "get", pos(spreadsheetId), pos(readRange)], { account });
       } catch (err) {
         return diagnose(err);
       }
@@ -35538,7 +35843,7 @@ function registerSheetsTools(server) {
         );
       }
     }
-    const args = ["sheets", "update", spreadsheetId, range, `--values-json=${JSON.stringify(values)}`];
+    const args = ["sheets", "update", pos(spreadsheetId), pos(range), `--values-json=${JSON.stringify(values)}`];
     if (dry_run) args.push("--dry-run");
     if (fail_on_formula_error) args.push("--fail-on-formula-error");
     return runOrDiagnose(args, { account });
@@ -35554,7 +35859,7 @@ function registerSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, range, values, account, dry_run }) => {
-    const args = ["sheets", "append", spreadsheetId, range, `--values-json=${JSON.stringify(values)}`];
+    const args = ["sheets", "append", pos(spreadsheetId), pos(range), `--values-json=${JSON.stringify(values)}`];
     if (dry_run) args.push("--dry-run");
     return runOrDiagnose(args, { account });
   });
@@ -35568,7 +35873,7 @@ function registerSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, range, account, dry_run }) => {
-    const args = ["sheets", "clear", spreadsheetId, range];
+    const args = ["sheets", "clear", pos(spreadsheetId), pos(range)];
     if (dry_run) args.push("--dry-run");
     return runOrDiagnose(args, { account });
   });
@@ -35580,7 +35885,7 @@ function registerSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, account }) => {
-    return runOrDiagnose(["sheets", "metadata", spreadsheetId], { account });
+    return runOrDiagnose(["sheets", "metadata", pos(spreadsheetId)], { account });
   });
   server.registerTool("gog_sheets_create", {
     description: "Create a new Google Spreadsheet. Returns JSON with the new spreadsheetId and URL.",
@@ -35590,7 +35895,7 @@ function registerSheetsTools(server) {
       account: accountParam
     })
   }, async ({ title, account }) => {
-    return runOrDiagnose(["sheets", "create", title], { account });
+    return runOrDiagnose(["sheets", "create", pos(title)], { account });
   });
   server.registerTool("gog_sheets_find_replace", {
     description: "Find and replace text across an entire Google Spreadsheet.",
@@ -35602,16 +35907,16 @@ function registerSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, find, replace, account }) => {
-    return runOrDiagnose(["sheets", "find-replace", spreadsheetId, find, replace], { account });
+    return runOrDiagnose(["sheets", "find-replace", pos(spreadsheetId), pos(find), pos(replace)], { account });
   });
   registerRunTool(server, { service: "sheets", examples: '"freeze", "add-tab", "rename-tab"' });
 }
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "4.2.5" : "0.0.0";
+var VERSION = true ? "4.3.0" : "0.0.0";
 
 // ../gogcli-mcp/src/bootstrap-auth.ts
-import { join as join2 } from "node:path";
+import { join as join5 } from "node:path";
 var AUTH_BOOTSTRAP_MARKER = "auth-bootstrap.sha256";
 var VARS = ["GOG_CLIENT_ID", "GOG_CLIENT_SECRET", "GOG_REFRESH_TOKEN", "GOG_ACCOUNT"];
 var log = (line) => {
@@ -35648,8 +35953,8 @@ async function bootstrapGogAuth(env = process.env, options = {}) {
     const { createHash } = await import("node:crypto");
     const { mkdir, readFile, writeFile, chmod } = await import("node:fs/promises");
     const home = options.home ?? (await import("node:os")).homedir();
-    const dir = join2(home, ".gogcli-mcp");
-    const marker = join2(dir, AUTH_BOOTSTRAP_MARKER);
+    const dir = join5(home, ".gogcli-mcp");
+    const marker = join5(dir, AUTH_BOOTSTRAP_MARKER);
     const fingerprint = createHash("sha256").update(values.join("\0")).digest("hex");
     const previous = await readFile(marker, "utf8").catch(() => void 0);
     if (previous === fingerprint && await accountListed(account, spawner)) return "present";
@@ -35700,7 +36005,7 @@ function hexToRgb(hex3) {
 }
 async function checkDateFormatTarget(spreadsheetId, range, account) {
   const peek = await runOrDiagnose(
-    ["sheets", "get", spreadsheetId, range, "--render=UNFORMATTED_VALUE"],
+    ["sheets", "get", pos(spreadsheetId), pos(range), "--render=UNFORMATTED_VALUE"],
     { account }
   );
   let parsed;
@@ -35735,7 +36040,7 @@ function registerExtraSheetsTools(server) {
     })
   }, async ({ spreadsheetId, account }) => {
     return runOrDiagnose(
-      ["sheets", "metadata", spreadsheetId, "--select=sheets.properties.sheetId,sheets.properties.title,sheets.properties.index,sheets.properties.gridProperties"],
+      ["sheets", "metadata", pos(spreadsheetId), "--select=sheets.properties.sheetId,sheets.properties.title,sheets.properties.index,sheets.properties.gridProperties"],
       { account }
     );
   });
@@ -35748,7 +36053,7 @@ function registerExtraSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, tabName, account }) => {
-    return runOrDiagnose(["sheets", "add-tab", spreadsheetId, tabName], { account });
+    return runOrDiagnose(["sheets", "add-tab", pos(spreadsheetId), pos(tabName)], { account });
   });
   server.registerTool("gog_sheets_delete_tab", {
     description: "Delete a sheet tab from a spreadsheet.",
@@ -35759,7 +36064,7 @@ function registerExtraSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, tabName, account }) => {
-    return runOrDiagnose(["sheets", "delete-tab", spreadsheetId, tabName, "--force"], { account });
+    return runOrDiagnose(["sheets", "delete-tab", pos(spreadsheetId), pos(tabName), "--force"], { account });
   });
   server.registerTool("gog_sheets_rename_tab", {
     description: "Rename a sheet tab.",
@@ -35771,7 +36076,7 @@ function registerExtraSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, oldName, newName, account }) => {
-    return runOrDiagnose(["sheets", "rename-tab", spreadsheetId, oldName, newName], { account });
+    return runOrDiagnose(["sheets", "rename-tab", pos(spreadsheetId), pos(oldName), pos(newName)], { account });
   });
   server.registerTool("gog_sheets_copy", {
     description: "Copy a spreadsheet to a new spreadsheet with the given title.",
@@ -35783,13 +36088,14 @@ function registerExtraSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, title, parent, account }) => {
-    const args = ["sheets", "copy", spreadsheetId, title];
+    const args = ["sheets", "copy", pos(spreadsheetId), pos(title)];
     if (parent) args.push(`--parent=${parent}`);
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_sheets_export", {
     description: "Export a spreadsheet as CSV, TSV, or PDF.",
-    annotations: { readOnlyHint: true },
+    // Writes a file on the gog host and can overwrite one: not read-only (audit SEC-4).
+    annotations: { readOnlyHint: false, destructiveHint: true },
     inputSchema: external_exports.object({
       spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
       format: external_exports.string().optional().describe("Export format: csv, tsv, pdf (default: csv)"),
@@ -35798,7 +36104,8 @@ function registerExtraSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, format, out, overwrite, account }) => {
-    const args = ["sheets", "export", spreadsheetId];
+    if (out) confinePath(out, "out");
+    const args = ["sheets", "export", pos(spreadsheetId)];
     if (format) args.push(`--format=${format}`);
     if (out) args.push(`--out=${out}`);
     if (overwrite) args.push("--overwrite");
@@ -35815,7 +36122,7 @@ function registerExtraSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, rows, cols, sheet, account }) => {
-    const args = ["sheets", "freeze", spreadsheetId];
+    const args = ["sheets", "freeze", pos(spreadsheetId)];
     if (rows !== void 0) args.push(`--rows=${rows}`);
     if (cols !== void 0) args.push(`--cols=${cols}`);
     if (sheet) args.push(`--sheet=${sheet}`);
@@ -35836,7 +36143,7 @@ function registerExtraSheetsTools(server) {
     })
   }, async ({ spreadsheetId, sheet, dimension, start, count, after, inheritFromBefore, account }) => {
     const effectiveStart = start + 1;
-    const args = ["sheets", "insert", spreadsheetId, sheet, dimension, String(effectiveStart)];
+    const args = ["sheets", "insert", pos(spreadsheetId), pos(sheet), pos(dimension), pos(String(effectiveStart))];
     if (count !== void 0) args.push(`--count=${count}`);
     if (after) args.push("--after");
     if (inheritFromBefore !== void 0) args.push(`--inherit-from-before=${inheritFromBefore}`);
@@ -35854,7 +36161,7 @@ function registerExtraSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, source, dest, type, transpose, account }) => {
-    const args = ["sheets", "copy-paste", spreadsheetId, source, dest];
+    const args = ["sheets", "copy-paste", pos(spreadsheetId), pos(source), pos(dest)];
     if (type) args.push(`--type=${type}`);
     if (transpose) args.push("--transpose");
     return runOrDiagnose(args, { account });
@@ -35869,7 +36176,7 @@ function registerExtraSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, range, type, account }) => {
-    const args = ["sheets", "merge", spreadsheetId, range];
+    const args = ["sheets", "merge", pos(spreadsheetId), pos(range)];
     if (type) args.push(`--type=${type}`);
     return runOrDiagnose(args, { account });
   });
@@ -35882,7 +36189,7 @@ function registerExtraSheetsTools(server) {
       account: accountParam
     })
   }, async ({ spreadsheetId, range, account }) => {
-    return runOrDiagnose(["sheets", "unmerge", spreadsheetId, range], { account });
+    return runOrDiagnose(["sheets", "unmerge", pos(spreadsheetId), pos(range)], { account });
   });
   server.registerTool("gog_sheets_format", {
     description: "Apply cell formatting to a range. The named flags (bold, italic, backgroundColor, etc.) compose into a Sheets API CellFormat \u2014 use them for the 90% case. For full API control, pass formatJson + formatFields (Sheets CellFormat + field mask) directly.",
@@ -35968,7 +36275,7 @@ function registerExtraSheetsTools(server) {
       formatJson = JSON.stringify(cellFormat);
       if (!formatFields) formatFields = fields.join(",");
     }
-    const args = ["sheets", "format", a.spreadsheetId, a.range, `--format-json=${formatJson}`];
+    const args = ["sheets", "format", pos(a.spreadsheetId), pos(a.range), `--format-json=${formatJson}`];
     if (formatFields) args.push(`--format-fields=${formatFields}`);
     return runOrDiagnose(args, { account: a.account });
   });
@@ -35986,7 +36293,7 @@ function registerExtraSheetsTools(server) {
   }, async ({ spreadsheetId, range, type, pattern, force, account }) => {
     const isDateType = type === "DATE" || type === "DATE_TIME";
     const warning = isDateType && !force ? await checkDateFormatTarget(spreadsheetId, range, account) : null;
-    const args = ["sheets", "number-format", spreadsheetId, range];
+    const args = ["sheets", "number-format", pos(spreadsheetId), pos(range)];
     if (type) args.push(`--type=${type}`);
     if (pattern) args.push(`--pattern=${pattern}`);
     const result = await runOrDiagnose(args, { account });
@@ -36007,7 +36314,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, range, effective, account }) => {
-    const args = ["sheets", "read-format", spreadsheetId, range];
+    const args = ["sheets", "read-format", pos(spreadsheetId), pos(range)];
     if (effective) args.push("--effective");
     return runOrDiagnose(args, { account });
   });
@@ -36022,7 +36329,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, columns, width, auto, account }) => {
-    const args = ["sheets", "resize-columns", spreadsheetId, columns];
+    const args = ["sheets", "resize-columns", pos(spreadsheetId), pos(columns)];
     if (width !== void 0) args.push(`--width=${width}`);
     if (auto) args.push("--auto");
     return runOrDiagnose(args, { account });
@@ -36038,7 +36345,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, rows, height, auto, account }) => {
-    const args = ["sheets", "resize-rows", spreadsheetId, rows];
+    const args = ["sheets", "resize-rows", pos(spreadsheetId), pos(rows)];
     if (height !== void 0) args.push(`--height=${height}`);
     if (auto) args.push("--auto");
     return runOrDiagnose(args, { account });
@@ -36052,7 +36359,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, range, account }) => {
-    return runOrDiagnose(["sheets", "notes", spreadsheetId, range], { account });
+    return runOrDiagnose(["sheets", "notes", pos(spreadsheetId), pos(range)], { account });
   });
   server.registerTool("gog_sheets_update_note", {
     description: "Add, update, or clear a cell note. Pass an empty string to clear the note.",
@@ -36065,7 +36372,7 @@ ${resultText2(result) ?? ""}` }] };
     })
   }, async ({ spreadsheetId, range, note, account }) => {
     return runOrDiagnose(
-      ["sheets", "update-note", spreadsheetId, range, payloadArg("note", "note-file", note)],
+      ["sheets", "update-note", pos(spreadsheetId), pos(range), payloadArg("note", "note-file", note)],
       { account }
     );
   });
@@ -36078,7 +36385,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, range, account }) => {
-    return runOrDiagnose(["sheets", "links", spreadsheetId, range], { account });
+    return runOrDiagnose(["sheets", "links", pos(spreadsheetId), pos(range)], { account });
   });
   server.registerTool("gog_sheets_links_set", {
     description: "Set cell hyperlinks in a Google Sheet. Three modes: (1) single link \u2014 pass cell + url (+ optional text); (2) multi-link cell \u2014 pass cell + runsJson, a JSON array of rich-text runs (a run with an empty uri is plain text); (3) batch \u2014 pass cellsJson, a JSON array of {cell,url,text} or {cell,runs:[...]} objects written in one request.",
@@ -36093,10 +36400,11 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, cell, url: url2, text, runsJson, cellsJson, account }) => {
-    const args = ["sheets", "links", "set", spreadsheetId];
-    if (cell) args.push(cell);
-    if (url2) args.push(url2);
-    if (text) args.push(text);
+    if (cellsJson) confineAtFile(cellsJson, "cellsJson");
+    const args = ["sheets", "links", "set", pos(spreadsheetId)];
+    if (cell) args.push(pos(cell));
+    if (url2) args.push(pos(url2));
+    if (text) args.push(pos(text));
     if (runsJson) args.push(`--runs-json=${runsJson}`);
     if (cellsJson) args.push(`--cells-json=${cellsJson}`);
     return runOrDiagnose(args, { account });
@@ -36110,7 +36418,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, range, account }) => {
-    return runOrDiagnose(["sheets", "validation", "get", spreadsheetId, range], { account });
+    return runOrDiagnose(["sheets", "validation", "get", pos(spreadsheetId), pos(range)], { account });
   });
   server.registerTool("gog_sheets_validation_set", {
     description: "Set a data-validation rule on a range \u2014 dropdowns (ONE_OF_LIST / ONE_OF_RANGE), checkboxes (BOOLEAN), number/date conditions, or custom formulas. Overwrites any existing rule on the range. Repeat values for list entries or between-bounds.",
@@ -36127,7 +36435,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, range, type, values, strict, inputMessage, showCustomUi, filteredRowsIncluded, account }) => {
-    const args = ["sheets", "validation", "set", spreadsheetId, range, `--type=${type}`];
+    const args = ["sheets", "validation", "set", pos(spreadsheetId), pos(range), `--type=${type}`];
     if (values) for (const v of values) args.push(`--value=${v}`);
     if (strict) args.push("--strict");
     if (inputMessage) args.push(`--input-message=${inputMessage}`);
@@ -36145,7 +36453,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, range, filteredRowsIncluded, account }) => {
-    const args = ["sheets", "validation", "clear", spreadsheetId, range];
+    const args = ["sheets", "validation", "clear", pos(spreadsheetId), pos(range)];
     if (filteredRowsIncluded) args.push("--filtered-rows-included");
     return runOrDiagnose(args, { account });
   });
@@ -36161,7 +36469,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, rangeOrSheet, dimension, start, end, account }) => {
-    const args = ["sheets", "delete-dimension", spreadsheetId, rangeOrSheet, `--dimension=${dimension}`];
+    const args = ["sheets", "delete-dimension", pos(spreadsheetId), pos(rangeOrSheet), `--dimension=${dimension}`];
     if (start !== void 0) args.push(`--start=${start}`);
     if (end !== void 0) args.push(`--end=${end}`);
     args.push("--force");
@@ -36175,7 +36483,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, account }) => {
-    return runOrDiagnose(["sheets", "named-ranges", "list", spreadsheetId], { account });
+    return runOrDiagnose(["sheets", "named-ranges", "list", pos(spreadsheetId)], { account });
   });
   server.registerTool("gog_sheets_named_ranges_get", {
     description: "Get a named range by name or ID.",
@@ -36186,7 +36494,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, nameOrId, account }) => {
-    return runOrDiagnose(["sheets", "named-ranges", "get", spreadsheetId, nameOrId], { account });
+    return runOrDiagnose(["sheets", "named-ranges", "get", pos(spreadsheetId), pos(nameOrId)], { account });
   });
   server.registerTool("gog_sheets_named_ranges_add", {
     description: "Create a new named range.",
@@ -36198,7 +36506,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, name, range, account }) => {
-    return runOrDiagnose(["sheets", "named-ranges", "add", spreadsheetId, name, range], { account });
+    return runOrDiagnose(["sheets", "named-ranges", "add", pos(spreadsheetId), pos(name), pos(range)], { account });
   });
   server.registerTool("gog_sheets_named_ranges_update", {
     description: "Update a named range (change its name, range, or both).",
@@ -36211,7 +36519,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, nameOrId, name, range, account }) => {
-    const args = ["sheets", "named-ranges", "update", spreadsheetId, nameOrId];
+    const args = ["sheets", "named-ranges", "update", pos(spreadsheetId), pos(nameOrId)];
     if (name) args.push(`--name=${name}`);
     if (range) args.push(`--range=${range}`);
     return runOrDiagnose(args, { account });
@@ -36225,7 +36533,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, nameOrId, account }) => {
-    return runOrDiagnose(["sheets", "named-ranges", "delete", spreadsheetId, nameOrId], { account });
+    return runOrDiagnose(["sheets", "named-ranges", "delete", pos(spreadsheetId), pos(nameOrId)], { account });
   });
   server.registerTool("gog_sheets_batch_update", {
     description: `Update values in multiple ranges with one Sheets API request. dataJson is a JSON array of {range, values} objects \u2014 pass it inline as a literal JSON string. Atomic \u2014 either all ranges update or none do. (The CLI also accepts "@/path/to/file.json", but that file is read on the gog server's filesystem, not the caller's, so inline JSON is the right form for remote MCP callers.)`,
@@ -36240,7 +36548,8 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, dataJson, input: input2, includeValuesInResponse, responseRender, responseDateTimeRender, account }) => {
-    const args = ["sheets", "batch-update", spreadsheetId, `--data-json=${dataJson}`];
+    confineAtFile(dataJson, "dataJson");
+    const args = ["sheets", "batch-update", pos(spreadsheetId), `--data-json=${dataJson}`];
     if (input2) args.push(`--input=${input2}`);
     if (includeValuesInResponse) args.push("--include-values-in-response");
     if (responseRender) args.push(`--response-render=${responseRender}`);
@@ -36258,7 +36567,7 @@ ${resultText2(result) ?? ""}` }] };
     })
   }, async ({ spreadsheetId, tab, to, account }) => {
     return runOrDiagnose(
-      ["sheets", "reorder-tab", spreadsheetId, `--tab=${tab}`, `--to=${to}`],
+      ["sheets", "reorder-tab", pos(spreadsheetId), `--tab=${tab}`, `--to=${to}`],
       { account }
     );
   });
@@ -36270,7 +36579,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, account }) => {
-    return runOrDiagnose(["sheets", "chart", "list", spreadsheetId], { account });
+    return runOrDiagnose(["sheets", "chart", "list", pos(spreadsheetId)], { account });
   });
   server.registerTool("gog_sheets_chart_get", {
     description: "Get the full definition (spec + position) of a single chart by its numeric chart ID.",
@@ -36281,7 +36590,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, chartId, account }) => {
-    return runOrDiagnose(["sheets", "chart", "get", spreadsheetId, chartId], { account });
+    return runOrDiagnose(["sheets", "chart", "get", pos(spreadsheetId), pos(chartId)], { account });
   });
   server.registerTool("gog_sheets_chart_create", {
     description: "Create an embedded chart from a JSON spec. specJson is a Sheets API ChartSpec (or full EmbeddedChart) \u2014 inline or @/path/to/file.json. Anchor the chart with sheet + anchor (A1 cell), and optionally size it with width/height pixels.",
@@ -36296,7 +36605,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, specJson, sheet, anchor: anchor2, width, height, account }) => {
-    const args = ["sheets", "chart", "create", spreadsheetId, `--spec-json=${specJson}`];
+    const args = ["sheets", "chart", "create", pos(spreadsheetId), `--spec-json=${specJson}`];
     if (sheet) args.push(`--sheet=${sheet}`);
     if (anchor2) args.push(`--anchor=${anchor2}`);
     if (width !== void 0) args.push(`--width=${width}`);
@@ -36314,7 +36623,7 @@ ${resultText2(result) ?? ""}` }] };
     })
   }, async ({ spreadsheetId, chartId, specJson, account }) => {
     return runOrDiagnose(
-      ["sheets", "chart", "update", spreadsheetId, chartId, `--spec-json=${specJson}`],
+      ["sheets", "chart", "update", pos(spreadsheetId), pos(chartId), `--spec-json=${specJson}`],
       { account }
     );
   });
@@ -36327,7 +36636,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, chartId, account }) => {
-    return runOrDiagnose(["sheets", "chart", "delete", spreadsheetId, chartId, "--force"], { account });
+    return runOrDiagnose(["sheets", "chart", "delete", pos(spreadsheetId), pos(chartId), "--force"], { account });
   });
   server.registerTool("gog_sheets_table_list", {
     description: "List Google Sheets tables in a spreadsheet (tableId, name, range).",
@@ -36337,7 +36646,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, account }) => {
-    return runOrDiagnose(["sheets", "table", "list", spreadsheetId], { account });
+    return runOrDiagnose(["sheets", "table", "list", pos(spreadsheetId)], { account });
   });
   server.registerTool("gog_sheets_table_get", {
     description: "Get a single Google Sheets table (definition + columns) by its table ID.",
@@ -36348,7 +36657,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, tableId, account }) => {
-    return runOrDiagnose(["sheets", "table", "get", spreadsheetId, tableId], { account });
+    return runOrDiagnose(["sheets", "table", "get", pos(spreadsheetId), pos(tableId)], { account });
   });
   server.registerTool("gog_sheets_table_create", {
     description: "Create a Google Sheets table over a range. columnsJson is a JSON array of column definitions (each {columnName, columnType?}); valid columnType values: TEXT, DOUBLE, BOOLEAN, DATE, DROPDOWN. Inline JSON or @/path/to/file.json.",
@@ -36362,7 +36671,7 @@ ${resultText2(result) ?? ""}` }] };
     })
   }, async ({ spreadsheetId, range, name, columnsJson, account }) => {
     return runOrDiagnose(
-      ["sheets", "table", "create", spreadsheetId, range, `--name=${name}`, `--columns-json=${columnsJson}`],
+      ["sheets", "table", "create", pos(spreadsheetId), pos(range), `--name=${name}`, `--columns-json=${columnsJson}`],
       { account }
     );
   });
@@ -36377,7 +36686,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, tableId, valuesJson, input: input2, account }) => {
-    const args = ["sheets", "table", "append", spreadsheetId, tableId, `--values-json=${valuesJson}`];
+    const args = ["sheets", "table", "append", pos(spreadsheetId), pos(tableId), `--values-json=${valuesJson}`];
     if (input2) args.push(`--input=${input2}`);
     return runOrDiagnose(args, { account });
   });
@@ -36390,7 +36699,7 @@ ${resultText2(result) ?? ""}` }] };
       account: accountParam
     })
   }, async ({ spreadsheetId, tableId, account }) => {
-    return runOrDiagnose(["sheets", "table", "clear", spreadsheetId, tableId, "--force"], { account });
+    return runOrDiagnose(["sheets", "table", "clear", pos(spreadsheetId), pos(tableId), "--force"], { account });
   });
   server.registerTool("gog_sheets_table_delete", {
     description: "Delete a Google Sheets table. WARNING: the underlying `gog`/Sheets behaviour is that deleting a table also DESTROYS every cell value in the table range \u2014 not just the table styling/columns. By default this tool prevents that data loss by emulating the Sheets UI's \"Convert to range\": it reads the table's cells (values AND formulas) first, deletes the table, then restores the data into the now-plain range. Formatting and banding are still lost; data-validation dropdowns are also not restored automatically, but you can snapshot them first with gog_sheets_validation_get and re-apply with gog_sheets_validation_set. Set keep_data=false to delete the table AND wipe its cell data (the raw destructive behaviour). To preserve everything, snapshot the whole spreadsheet first with gog_sheets_snapshot.",
@@ -36405,27 +36714,27 @@ ${resultText2(result) ?? ""}` }] };
     })
   }, async ({ spreadsheetId, tableId, keep_data = true, account }) => {
     if (!keep_data) {
-      return runOrDiagnose(["sheets", "table", "delete", spreadsheetId, tableId, "--discard-data", "--force"], { account });
+      return runOrDiagnose(["sheets", "table", "delete", pos(spreadsheetId), pos(tableId), "--discard-data", "--force"], { account });
     }
     let range;
     let values;
     try {
-      const parsed = JSON.parse(await run(["sheets", "table", "get", spreadsheetId, tableId], { account }));
+      const parsed = JSON.parse(await run(["sheets", "table", "get", pos(spreadsheetId), pos(tableId)], { account }));
       range = parsed.table?.a1;
       if (!range) throw new Error(`could not determine the table's range (no "a1" in table get output) for table ${tableId}`);
-      const read = JSON.parse(await run(["sheets", "get", spreadsheetId, range, "--render=FORMULA"], { account }));
+      const read = JSON.parse(await run(["sheets", "get", pos(spreadsheetId), pos(range), "--render=FORMULA"], { account }));
       values = read.values ?? [];
     } catch (err) {
       return diagnose(err);
     }
     try {
-      await run(["sheets", "table", "delete", spreadsheetId, tableId, "--discard-data", "--force"], { account });
+      await run(["sheets", "table", "delete", pos(spreadsheetId), pos(tableId), "--discard-data", "--force"], { account });
     } catch (err) {
       return diagnose(err);
     }
     if (values.length > 0) {
       try {
-        await run(["sheets", "update", spreadsheetId, range, `--values-json=${JSON.stringify(values)}`], { account });
+        await run(["sheets", "update", pos(spreadsheetId), pos(range), `--values-json=${JSON.stringify(values)}`], { account });
       } catch (err) {
         return rawTextResult(
           `Table ${tableId} was deleted, but restoring its data FAILED \u2014 re-apply the values below manually.
@@ -36448,7 +36757,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, sheet, account }) => {
-    const args = ["sheets", "banding", "list", spreadsheetId];
+    const args = ["sheets", "banding", "list", pos(spreadsheetId)];
     if (sheet) args.push(`--sheet=${sheet}`);
     return runOrDiagnose(args, { account });
   });
@@ -36463,7 +36772,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, range, rowPropertiesJson, columnPropertiesJson, account }) => {
-    const args = ["sheets", "banding", "set", spreadsheetId, range];
+    const args = ["sheets", "banding", "set", pos(spreadsheetId), pos(range)];
     if (rowPropertiesJson) args.push(`--row-properties-json=${rowPropertiesJson}`);
     if (columnPropertiesJson) args.push(`--column-properties-json=${columnPropertiesJson}`);
     return runOrDiagnose(args, { account });
@@ -36479,7 +36788,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, id, all, sheet, account }) => {
-    const args = ["sheets", "banding", "clear", spreadsheetId];
+    const args = ["sheets", "banding", "clear", pos(spreadsheetId)];
     if (id !== void 0) args.push(`--id=${id}`);
     if (all) args.push("--all");
     if (sheet) args.push(`--sheet=${sheet}`);
@@ -36496,7 +36805,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, range, replace, account }) => {
-    const args = ["sheets", "filter", "set", spreadsheetId, range];
+    const args = ["sheets", "filter", "set", pos(spreadsheetId), pos(range)];
     if (replace) args.push("--force");
     return runOrDiagnose(args, { account });
   });
@@ -36509,7 +36818,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, sheet, account }) => {
-    const args = ["sheets", "conditional-format", "list", spreadsheetId];
+    const args = ["sheets", "conditional-format", "list", pos(spreadsheetId)];
     if (sheet) args.push(`--sheet=${sheet}`);
     return runOrDiagnose(args, { account });
   });
@@ -36540,7 +36849,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, range, type, formatJson, expr, formatFields, gradientRuleJson, account }) => {
-    const args = ["sheets", "conditional-format", "add", spreadsheetId, range];
+    const args = ["sheets", "conditional-format", "add", pos(spreadsheetId), pos(range)];
     if (type) args.push(`--type=${type}`);
     if (formatJson !== void 0) args.push(`--format-json=${formatJson}`);
     if (expr !== void 0) args.push(`--expr=${expr}`);
@@ -36559,7 +36868,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, sheet, index, all, account }) => {
-    const args = ["sheets", "conditional-format", "clear", spreadsheetId, `--sheet=${sheet}`];
+    const args = ["sheets", "conditional-format", "clear", pos(spreadsheetId), `--sheet=${sheet}`];
     if (index !== void 0) args.push(`--index=${index}`);
     if (all) args.push("--all");
     args.push("--force");
@@ -36575,7 +36884,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, name, parent, account }) => {
-    const args = ["drive", "copy", spreadsheetId, name];
+    const args = ["drive", "copy", pos(spreadsheetId), pos(name)];
     if (parent) args.push(`--parent=${parent}`);
     return runOrDiagnose(args, { account });
   });
@@ -36588,7 +36897,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, account }) => {
-    return runOrDiagnose(["sheets", "datasource", "list", spreadsheetId], { account });
+    return runOrDiagnose(["sheets", "datasource", "list", pos(spreadsheetId)], { account });
   });
   server.registerTool("gog_sheets_datasource_describe", {
     description: "Describe one Connected Sheets data source in full: the complete API DataSource spec (including the BigQuery raw query, which gog_sheets_datasource_list withholds), its sheet properties, its DataExecutionStatus and any refresh schedules. Refreshes are asynchronous and this tool cannot start one \u2014 poll it until state is SUCCEEDED or FAILED, and read the status error text when it is FAILED." + bigQueryScopeNote,
@@ -36599,7 +36908,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, dataSourceId, account }) => {
-    return runOrDiagnose(["sheets", "datasource", "describe", spreadsheetId, dataSourceId], { account });
+    return runOrDiagnose(["sheets", "datasource", "describe", pos(spreadsheetId), pos(dataSourceId)], { account });
   });
   server.registerTool("gog_sheets_datasource_table_list", {
     description: `List the data-source tables \u2014 "extracts" in the Sheets editor \u2014 anchored in a spreadsheet. A data-source table has NO id of its own in the Sheets API: its definition lives on its top-left cell, so every extract is identified by a sheet-qualified A1 anchor (e.g. "Extracts!B3"). That anchor is what the describe and read tools take. Filter with dataSourceId to see only one source's extracts.` + bigQueryScopeNote,
@@ -36610,7 +36919,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, dataSourceId, account }) => {
-    const args = ["sheets", "datasource", "table", "list", spreadsheetId];
+    const args = ["sheets", "datasource", "table", "list", pos(spreadsheetId)];
     if (dataSourceId) args.push(`--data-source-id=${dataSourceId}`);
     return runOrDiagnose(args, { account });
   });
@@ -36623,7 +36932,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, anchor: anchor2, account }) => {
-    return runOrDiagnose(["sheets", "datasource", "table", "describe", spreadsheetId, anchor2], { account });
+    return runOrDiagnose(["sheets", "datasource", "table", "describe", pos(spreadsheetId), pos(anchor2)], { account });
   });
   server.registerTool("gog_sheets_datasource_table_read", {
     description: 'Read the values out of the data-source table (extract) anchored at an A1 cell. Bounded on purpose: at most maxRows data rows (gog default 1000) plus the header row, which is returned separately. The JSON reports "truncated": true when the configured extract can hold more rows than were returned \u2014 treat that exactly like a truncated search, i.e. do not conclude a value is absent from it; raise maxRows or narrow the extract instead. Use render=UNFORMATTED_VALUE for arithmetic (FORMATTED_VALUE returns display strings) or render=FORMULA to see the cell formulas.' + bigQueryScopeNote,
@@ -36636,7 +36945,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, anchor: anchor2, maxRows, render, account }) => {
-    const args = ["sheets", "datasource", "table", "read", spreadsheetId, anchor2];
+    const args = ["sheets", "datasource", "table", "read", pos(spreadsheetId), pos(anchor2)];
     if (maxRows !== void 0) args.push(`--max-rows=${maxRows}`);
     if (render) args.push(`--render=${render}`);
     return runOrDiagnose(args, { account });
@@ -36662,7 +36971,7 @@ ${errorText(err)}`
     if (query === void 0 && !(dataset && table)) {
       throw new Error("Pass query, or both --dataset and --table (tableProject alone is not a table).");
     }
-    const args = ["sheets", "datasource", "add", spreadsheetId, `--billing-project=${billingProject}`];
+    const args = ["sheets", "datasource", "add", pos(spreadsheetId), `--billing-project=${billingProject}`];
     if (query !== void 0) args.push(`--query=${query}`);
     if (tableProject) args.push(`--table-project=${tableProject}`);
     if (dataset) args.push(`--dataset=${dataset}`);
@@ -36690,7 +36999,7 @@ ${errorText(err)}`
     if (billingProject === void 0 && query === void 0 && !tableFlags) {
       throw new Error("nothing to update: pass billingProject, query, dataset, table or tableProject.");
     }
-    const args = ["sheets", "datasource", "update", spreadsheetId, dataSourceId];
+    const args = ["sheets", "datasource", "update", pos(spreadsheetId), pos(dataSourceId)];
     if (billingProject !== void 0) args.push(`--billing-project=${billingProject}`);
     if (query !== void 0) args.push(`--query=${query}`);
     if (tableProject !== void 0) args.push(`--table-project=${tableProject}`);
@@ -36708,7 +37017,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, dataSourceId, forceRefresh, account }) => {
-    const args = ["sheets", "datasource", "refresh", spreadsheetId, dataSourceId];
+    const args = ["sheets", "datasource", "refresh", pos(spreadsheetId), pos(dataSourceId)];
     if (forceRefresh) args.push("--force-refresh");
     return runOrDiagnose(args, { account });
   });
@@ -36721,7 +37030,7 @@ ${errorText(err)}`
       account: accountParam
     })
   }, async ({ spreadsheetId, dataSourceId, account }) => {
-    return runOrDiagnose(["sheets", "datasource", "delete", spreadsheetId, dataSourceId, "--force"], { account });
+    return runOrDiagnose(["sheets", "datasource", "delete", pos(spreadsheetId), pos(dataSourceId), "--force"], { account });
   });
 }