gogcli-mcp-docs 4.2.5 → 4.4.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,107 @@ 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;
+}
+
+// ../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) {
@@ -35127,9 +35404,17 @@ function pushPaginationFlags(args, p) {
   if (p.all) args.push("--all");
 }
 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")
@@ -35143,7 +35428,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) {
@@ -35264,7 +35563,13 @@ function formatAuthHealth(raw, now) {
   return accounts.map((a) => formatOneAccountHealth(a, now)).join("\n\n");
 }
 
+// ../gogcli-mcp/src/dispatch-confirmation.ts
+var confirmTokenParam = external_exports.string().optional().describe(
+  `ONLY for the two-step fallback (client without MCP elicitation, server with GOG_SEND_CONFIRM_FALLBACK=token). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat \u2014 never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.`
+);
+
 // ../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.";
@@ -35322,7 +35627,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,
@@ -35342,7 +35647,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) {
@@ -35369,7 +35674,7 @@ function registerAuthToolsWith(server, defaultServices) {
       const args = [
         "auth",
         "add",
-        email3,
+        pos(email3),
         "--remote",
         "--step",
         "2",
@@ -35389,6 +35694,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."
   });
 }
@@ -35436,7 +35742,7 @@ function registerDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, account }) => {
-    return runOrDiagnose(["docs", "info", docId], { account });
+    return runOrDiagnose(["docs", "info", pos(docId)], { account });
   });
   server.registerTool("gog_docs_cat", {
     description: "Read a Google Doc as plain text.",
@@ -35447,7 +35753,7 @@ function registerDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, chips, account }) => {
-    const args = ["docs", "cat", docId];
+    const args = ["docs", "cat", pos(docId)];
     if (chips) args.push("--chips");
     return runOrDiagnose(args, { account });
   });
@@ -35459,7 +35765,7 @@ function registerDocsTools(server) {
       account: accountParam
     })
   }, async ({ title, account }) => {
-    return runOrDiagnose(["docs", "create", title], { account });
+    return runOrDiagnose(["docs", "create", pos(title)], { account });
   });
   server.registerTool("gog_docs_write", {
     description: "Write text content to a Google Doc, replacing existing body content by default. Set append=true to add after existing content.",
@@ -35484,7 +35790,7 @@ function registerDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, text, append, checkOrphans, bullets, bulletPreset, ordered, noBullets, indentStart, indentEnd, indentFirstLine, spaceAbove, spaceBelow, keepLinesTogether, keepWithNext, batch, account }) => {
-    const args = ["docs", "write", docId, `--text=${text}`];
+    const args = ["docs", "write", pos(docId), `--text=${text}`];
     if (append) args.push("--append");
     if (checkOrphans) args.push("--check-orphans");
     if (bullets) args.push("--bullets");
@@ -35511,7 +35817,7 @@ function registerDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, find, replace, account }) => {
-    return runOrDiagnose(["docs", "find-replace", docId, find, replace], { account });
+    return runOrDiagnose(["docs", "find-replace", pos(docId), pos(find), pos(replace)], { account });
   });
   server.registerTool("gog_docs_structure", {
     description: "Show a Google Doc's structure with numbered paragraphs. Useful for understanding the document layout before making index-based edits.",
@@ -35521,7 +35827,7 @@ function registerDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, account }) => {
-    return runOrDiagnose(["docs", "structure", docId], { account });
+    return runOrDiagnose(["docs", "structure", pos(docId)], { account });
   });
   registerRunTool(server, { service: "docs", examples: '"copy", "clear", "insert", "sed", "export"' });
 }
@@ -35538,7 +35844,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."),
@@ -35547,7 +35853,7 @@ var replySchema = {
   signatureFile: external_exports.string().optional().describe("Append a local signature file (plain text or HTML), read on the gog server"),
   account: accountParam
 };
-var sendReplySchema = external_exports.object(replySchema);
+var sendReplySchema = external_exports.object({ ...replySchema, confirmToken: confirmTokenParam });
 
 // ../gogcli-mcp/src/tools/sheets.ts
 var cellValueParam = external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean(), external_exports.null()]);
@@ -35559,10 +35865,10 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "4.2.5" : "0.0.0";
+var VERSION = true ? "4.4.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) => {
@@ -35599,8 +35905,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";
@@ -35645,7 +35951,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, title, parent, account }) => {
-    const args = ["docs", "copy", docId, title];
+    const args = ["docs", "copy", pos(docId), pos(title)];
     if (parent) args.push(`--parent=${parent}`);
     return runOrDiagnose(args, { account });
   });
@@ -35668,7 +35974,7 @@ function registerExtraDocsTools(server) {
     const args = ["docs", "delete"];
     if (start !== void 0) args.push(`--start=${start}`);
     if (end !== void 0) args.push(`--end=${end}`);
-    args.push(docId);
+    args.push(pos(docId));
     if (at) args.push(`--at=${at}`);
     if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
     if (matchCase) args.push("--match-case");
@@ -35685,7 +35991,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, account }) => {
-    return runOrDiagnose(["drive", "delete", docId, "--force"], { account });
+    return runOrDiagnose(["drive", "delete", pos(docId), "--force"], { account });
   });
   server.registerTool("gog_docs_edit", {
     description: "Edit a Google Doc by finding and replacing text (stream-edit style).",
@@ -35698,7 +36004,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, find, replace, matchCase, account }) => {
-    const args = ["docs", "edit", docId, find, replace];
+    const args = ["docs", "edit", pos(docId), pos(find), pos(replace)];
     if (matchCase) args.push("--match-case");
     return runOrDiagnose(args, { account });
   });
@@ -35716,12 +36022,12 @@ function registerExtraDocsTools(server) {
     })
   }, async ({ docId, format, tab, allTabs, maxBytes, chips, account }) => {
     if (format === "json") {
-      const args2 = ["docs", "raw", docId, "--pretty"];
+      const args2 = ["docs", "raw", pos(docId), "--pretty"];
       if (tab) args2.push(`--tab=${tab}`);
       if (allTabs) args2.push("--all-tabs");
       return runOrDiagnose(args2, { account, lossless: true });
     }
-    const args = ["docs", "cat", docId];
+    const args = ["docs", "cat", pos(docId)];
     if (tab) args.push(`--tab=${tab}`);
     if (allTabs) args.push("--all-tabs");
     if (maxBytes !== void 0) args.push(`--max-bytes=${maxBytes}`);
@@ -35774,7 +36080,7 @@ function registerExtraDocsTools(server) {
     })
   }, async (args) => {
     const a = args;
-    const argv = ["docs", "format", a.docId];
+    const argv = ["docs", "format", pos(a.docId)];
     if (a.match) argv.push(`--match=${a.match}`);
     if (a.matchAll) argv.push("--match-all");
     if (a.matchCase) argv.push("--match-case");
@@ -35823,13 +36129,14 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, tab, account }) => {
-    const args = ["docs", "suggestions", "list", docId];
+    const args = ["docs", "suggestions", "list", pos(docId)];
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_docs_export", {
     description: "Export a Google Doc as PDF, plain text, HTML, DOCX, or other format.",
-    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({
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       format: external_exports.string().optional().describe("Export format: pdf, txt, html, docx, rtf, odt, epub (default: pdf)"),
@@ -35838,7 +36145,8 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, format, out, overwrite, account }) => {
-    const args = ["docs", "export", docId];
+    if (out) confinePath(out, "out");
+    const args = ["docs", "export", pos(docId)];
     if (format) args.push(`--format=${format}`);
     if (out) args.push(`--out=${out}`);
     if (overwrite) args.push("--overwrite");
@@ -35861,8 +36169,9 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, content, index, file: file2, at, occurrence, matchCase, tabId, segment, batch, account }) => {
-    const args = ["docs", "insert", docId];
-    if (content) args.push(content);
+    if (file2) confinePath(file2, "file");
+    const args = ["docs", "insert", pos(docId)];
+    if (content) args.push(pos(content));
     if (index !== void 0) args.push(`--index=${index}`);
     if (file2) args.push(`--file=${file2}`);
     if (at) args.push(`--at=${at}`);
@@ -35885,7 +36194,8 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, text, file: file2, markdown, tab, account }) => {
-    const args = ["docs", "write", docId, "--append"];
+    if (file2) confinePath(file2, "file");
+    const args = ["docs", "write", pos(docId), "--append"];
     if (text) args.push(`--text=${text}`);
     if (file2) args.push(`--file=${file2}`);
     if (markdown) args.push("--markdown");
@@ -35900,7 +36210,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, account }) => {
-    return runOrDiagnose(["docs", "list-tabs", docId], { account });
+    return runOrDiagnose(["docs", "list-tabs", pos(docId)], { account });
   });
   server.registerTool("gog_docs_sed", {
     description: "Stream-edit a Google Doc with sed-like regex expressions (s/find/replace/ syntax).",
@@ -35914,8 +36224,9 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, expression, expressions, file: file2, tab, account }) => {
-    const args = ["docs", "sed", docId];
-    if (expression) args.push(expression);
+    if (file2) confinePath(file2, "file");
+    const args = ["docs", "sed", pos(docId)];
+    if (expression) args.push(pos(expression));
     if (expressions) {
       for (const expr of expressions) {
         args.push(`--expressions=${expr}`);
@@ -35945,7 +36256,8 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, text, file: file2, index, replaceRange, markdown, at, occurrence, matchCase, tabId, segment, pageless, batch, account }) => {
-    const args = ["docs", "update", docId];
+    if (file2) confinePath(file2, "file");
+    const args = ["docs", "update", pos(docId)];
     if (text) args.push(`--text=${text}`);
     if (file2) args.push(`--file=${file2}`);
     if (index !== void 0) args.push(`--index=${index}`);
@@ -35973,7 +36285,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, includeResolved, since, locate, tab, max, page, all, account }) => {
-    const args = ["docs", "comments", "list", docId];
+    const args = ["docs", "comments", "list", pos(docId)];
     if (includeResolved) args.push("--include-resolved");
     if (since) args.push(`--since=${since}`);
     if (locate) args.push("--locate");
@@ -35990,7 +36302,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, commentId, account }) => {
-    return runOrDiagnose(["docs", "comments", "get", docId, commentId], { account });
+    return runOrDiagnose(["docs", "comments", "get", pos(docId), pos(commentId)], { account });
   });
   server.registerTool("gog_docs_comments_add", {
     description: "Add a comment to a Google Doc. Optionally attach quoted text that appears as the highlighted passage in the Google Docs UI.",
@@ -36002,7 +36314,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, content, quoted, account }) => {
-    const args = ["docs", "comments", "add", docId, content];
+    const args = ["docs", "comments", "add", pos(docId), pos(content)];
     if (quoted) args.push(`--quoted=${quoted}`);
     return runOrDiagnose(args, { account });
   });
@@ -36016,7 +36328,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, commentId, content, account }) => {
-    return runOrDiagnose(["docs", "comments", "reply", docId, commentId, content], { account });
+    return runOrDiagnose(["docs", "comments", "reply", pos(docId), pos(commentId), pos(content)], { account });
   });
   server.registerTool("gog_docs_comments_resolve", {
     description: "Resolve a comment (mark as done). Optionally include a closing message.",
@@ -36028,7 +36340,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, commentId, message, account }) => {
-    const args = ["docs", "comments", "resolve", docId, commentId];
+    const args = ["docs", "comments", "resolve", pos(docId), pos(commentId)];
     if (message) args.push(`--message=${message}`);
     return runOrDiagnose(args, { account });
   });
@@ -36041,7 +36353,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, commentId, account }) => {
-    return runOrDiagnose(["docs", "comments", "delete", docId, commentId, "--force"], { account });
+    return runOrDiagnose(["docs", "comments", "delete", pos(docId), pos(commentId), "--force"], { account });
   });
   server.registerTool("gog_docs_comments_reopen", {
     description: "Reopen a previously resolved comment (flip resolved \u2192 open).",
@@ -36052,7 +36364,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, commentId, account }) => {
-    return runOrDiagnose(["docs", "comments", "reopen", docId, commentId], { account });
+    return runOrDiagnose(["docs", "comments", "reopen", pos(docId), pos(commentId)], { account });
   });
   server.registerTool("gog_docs_comments_locate", {
     description: "Locate a comment's anchor in a Google Doc \u2014 resolves the comment's quoted text to its current Docs API index range, or reports the comment as orphaned if the quote can no longer be found (e.g. the anchored text was edited away). Read-only; useful before an index-based edit near a comment.",
@@ -36066,7 +36378,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, commentId, matchCase, normalizeWhitespace, tab, account }) => {
-    const args = ["docs", "comments", "locate", docId, commentId];
+    const args = ["docs", "comments", "locate", pos(docId), pos(commentId)];
     if (matchCase) args.push("--match-case");
     if (normalizeWhitespace) args.push("--normalize-whitespace");
     if (tab) args.push(`--tab=${tab}`);
@@ -36088,7 +36400,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, text, occurrence, matchCase, normalizeWhitespace, all, failEmpty, tab, segment, account }) => {
-    const args = ["docs", "find-range", docId, text];
+    const args = ["docs", "find-range", pos(docId), pos(text)];
     if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
     if (matchCase) args.push("--match-case");
     if (normalizeWhitespace) args.push("--normalize-whitespace");
@@ -36121,7 +36433,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ batchId, autoSplit, continueOnError, account }) => {
-    const args = ["batch", "end", batchId];
+    const args = ["batch", "end", pos(batchId)];
     if (autoSplit) args.push("--auto-split");
     if (continueOnError) args.push("--continue-on-error");
     return runOrDiagnose(args, { account });
@@ -36134,7 +36446,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ batchId, account }) => {
-    return runOrDiagnose(["batch", "abort", batchId], { account });
+    return runOrDiagnose(["batch", "abort", pos(batchId)], { account });
   });
   server.registerTool("gog_batch_list", {
     description: "List persisted Docs request batches (id, doc, label, request count, status).",
@@ -36153,7 +36465,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ batchId, account }) => {
-    return runOrDiagnose(["batch", "show", batchId], { account });
+    return runOrDiagnose(["batch", "show", pos(batchId)], { account });
   });
   server.registerTool("gog_batch_prune", {
     description: "Delete stale persisted batches (not updated within olderThan).",
@@ -36181,7 +36493,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, col, width, evenlyDistributed, tableIndex, tab, batch, account }) => {
-    const args = ["docs", "table-column-width", docId];
+    const args = ["docs", "table-column-width", pos(docId)];
     if (col !== void 0) args.push(`--col=${col}`);
     if (width !== void 0) args.push(`--width=${width}`);
     if (evenlyDistributed) args.push("--evenly-distributed");
@@ -36203,7 +36515,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, table, at, valuesJson, tab, account }) => {
-    const args = ["docs", "table-row", "insert", docId];
+    const args = ["docs", "table-row", "insert", pos(docId)];
     if (table) args.push(`--table=${table}`);
     if (at) args.push(`--at=${at}`);
     if (valuesJson) args.push(`--values-json=${valuesJson}`);
@@ -36221,7 +36533,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, row, table, tab, account }) => {
-    const args = ["docs", "table-row", "delete", docId, `--row=${row}`];
+    const args = ["docs", "table-row", "delete", pos(docId), `--row=${row}`];
     if (table) args.push(`--table=${table}`);
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
@@ -36237,7 +36549,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, table, at, tab, account }) => {
-    const args = ["docs", "table-column", "insert", docId];
+    const args = ["docs", "table-column", "insert", pos(docId)];
     if (at) args.push(`--at=${at}`);
     if (table) args.push(`--table=${table}`);
     if (tab) args.push(`--tab=${tab}`);
@@ -36254,7 +36566,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, col, table, tab, account }) => {
-    const args = ["docs", "table-column", "delete", docId, `--col=${col}`];
+    const args = ["docs", "table-column", "delete", pos(docId), `--col=${col}`];
     if (table) args.push(`--table=${table}`);
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
@@ -36270,7 +36582,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, range, table, tab, account }) => {
-    const args = ["docs", "table-merge", docId, `--range=${range}`];
+    const args = ["docs", "table-merge", pos(docId), `--range=${range}`];
     if (table) args.push(`--table=${table}`);
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
@@ -36286,7 +36598,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, cell, table, tab, account }) => {
-    const args = ["docs", "table-unmerge", docId, `--cell=${cell}`];
+    const args = ["docs", "table-unmerge", pos(docId), `--cell=${cell}`];
     if (table) args.push(`--table=${table}`);
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
@@ -36306,7 +36618,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, name, at, occurrence, matchCase, start, end, tab, account }) => {
-    const args = ["docs", "named-range", "create", docId, `--name=${name}`];
+    const args = ["docs", "named-range", "create", pos(docId), `--name=${name}`];
     if (at) args.push(`--at=${at}`);
     if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
     if (matchCase) args.push("--match-case");
@@ -36325,7 +36637,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, name, tab, account }) => {
-    const args = ["docs", "named-range", "list", docId];
+    const args = ["docs", "named-range", "list", pos(docId)];
     if (name) args.push(`--name=${name}`);
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
@@ -36340,7 +36652,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, nameOrId, tab, account }) => {
-    const args = ["docs", "named-range", "delete", docId, nameOrId];
+    const args = ["docs", "named-range", "delete", pos(docId), pos(nameOrId)];
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
   });
@@ -36356,7 +36668,8 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, nameOrId, text, file: file2, tab, account }) => {
-    const args = ["docs", "named-range", "replace", docId, nameOrId];
+    if (file2) confinePath(file2, "file");
+    const args = ["docs", "named-range", "replace", pos(docId), pos(nameOrId)];
     if (text !== void 0) args.push(`--text=${text}`);
     if (file2) args.push(`--file=${file2}`);
     if (tab) args.push(`--tab=${tab}`);
@@ -36371,7 +36684,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, tab, account }) => {
-    const args = ["docs", "tables", "list", docId];
+    const args = ["docs", "tables", "list", pos(docId)];
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
   });
@@ -36384,7 +36697,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, tab, account }) => {
-    const args = ["docs", "images", "list", docId];
+    const args = ["docs", "images", "list", pos(docId)];
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
   });
@@ -36398,7 +36711,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, level, tab, account }) => {
-    const args = ["docs", "headings", "list", docId];
+    const args = ["docs", "headings", "list", pos(docId)];
     if (level !== void 0) args.push(`--level=${level}`);
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
@@ -36413,7 +36726,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, style, tab, account }) => {
-    const args = ["docs", "paragraphs", "list", docId];
+    const args = ["docs", "paragraphs", "list", pos(docId)];
     if (style) args.push(`--style=${style}`);
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
@@ -36433,7 +36746,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, index, atEnd, at, occurrence, matchCase, tab, batch, account }) => {
-    const args = ["docs", "insert-page-break", docId];
+    const args = ["docs", "insert-page-break", pos(docId)];
     if (index !== void 0) args.push(`--index=${index}`);
     if (atEnd) args.push("--at-end");
     if (at) args.push(`--at=${at}`);
@@ -36459,7 +36772,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, layout, pageSize, pageWidth, pageHeight, marginTop, marginBottom, marginLeft, marginRight, account }) => {
-    const args = ["docs", "page-layout", docId];
+    const args = ["docs", "page-layout", pos(docId)];
     if (layout) args.push(`--layout=${layout}`);
     if (pageSize) args.push(`--page-size=${pageSize}`);
     if (pageWidth) args.push(`--page-width=${pageWidth}`);
@@ -36484,7 +36797,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, rows, cols, index, atEnd, valuesJson, tab, account }) => {
-    const args = ["docs", "insert-table", docId, `--rows=${rows}`, `--cols=${cols}`];
+    const args = ["docs", "insert-table", pos(docId), `--rows=${rows}`, `--cols=${cols}`];
     if (index !== void 0) args.push(`--index=${index}`);
     if (atEnd) args.push("--at-end");
     if (valuesJson !== void 0) args.push(`--values-json=${valuesJson}`);
@@ -36507,12 +36820,13 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, row, col, content, contentFile, append, format, tableIndex, tab, account }) => {
+    if (contentFile) confinePath(contentFile, "contentFile");
     if (content !== void 0 && contentFile) {
       throw new Error(
         'gog_docs_cell_update accepts content or contentFile, not both \u2014 gog refuses the combination ("cannot use both --content and --content-file"). Drop one of them.'
       );
     }
-    const args = ["docs", "cell-update", docId, `--row=${row}`, `--col=${col}`];
+    const args = ["docs", "cell-update", pos(docId), `--row=${row}`, `--col=${col}`];
     if (content !== void 0) args.push(payloadArg("content", "content-file", content, "md"));
     if (contentFile) args.push(`--content-file=${contentFile}`);
     if (append) args.push("--append");
@@ -36552,7 +36866,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, row, col, rowSpan, colSpan, backgroundColor, textColor, bold, italic, underline, borderAll, borderTop, borderBottom, borderLeft, borderRight, paddingAll, paddingTop, paddingBottom, paddingLeft, paddingRight, contentAlign, tableIndex, tab, batch, account }) => {
-    const args = ["docs", "cell-style", docId, `--row=${row}`, `--col=${col}`];
+    const args = ["docs", "cell-style", pos(docId), `--row=${row}`, `--col=${col}`];
     if (rowSpan !== void 0) args.push(`--row-span=${rowSpan}`);
     if (colSpan !== void 0) args.push(`--col-span=${colSpan}`);
     if (backgroundColor) args.push(`--background-color=${backgroundColor}`);
@@ -36595,7 +36909,8 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, file: file2, url: url2, at, before, after, width, height, name, parent, onRestricted, tab, account }) => {
-    const args = ["docs", "insert-image", docId];
+    if (file2) confinePath(file2, "file");
+    const args = ["docs", "insert-image", pos(docId)];
     if (file2) args.push(`--file=${file2}`);
     if (url2) args.push(`--url=${url2}`);
     if (at) args.push(`--at=${at}`);
@@ -36626,7 +36941,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, email: email3, index, atEnd, at, occurrence, matchCase, tab, batch, account }) => {
-    const args = ["docs", "insert-person", docId, `--email=${email3}`];
+    const args = ["docs", "insert-person", pos(docId), `--email=${email3}`];
     if (index !== void 0) args.push(`--index=${index}`);
     if (atEnd) args.push("--at-end");
     if (at) args.push(`--at=${at}`);
@@ -36650,7 +36965,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, date: date5, format, index, atEnd, tab, batch, account }) => {
-    const args = ["docs", "insert-date-chip", docId];
+    const args = ["docs", "insert-date-chip", pos(docId)];
     if (date5) args.push(`--date=${date5}`);
     if (format) args.push(`--format=${format}`);
     if (index !== void 0) args.push(`--index=${index}`);
@@ -36671,7 +36986,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, title, index, parentTab, iconEmoji, account }) => {
-    const args = ["docs", "add-tab", docId];
+    const args = ["docs", "add-tab", pos(docId)];
     if (title) args.push(`--title=${title}`);
     if (index !== void 0) args.push(`--index=${index}`);
     if (parentTab) args.push(`--parent-tab=${parentTab}`);
@@ -36688,7 +37003,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, tab, title, account }) => {
-    const args = ["docs", "rename-tab", docId, `--tab=${tab}`, `--title=${title}`];
+    const args = ["docs", "rename-tab", pos(docId), `--tab=${tab}`, `--title=${title}`];
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_docs_delete_tab", {
@@ -36700,7 +37015,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, tab, account }) => {
-    const args = ["docs", "delete-tab", docId, `--tab=${tab}`, "--force"];
+    const args = ["docs", "delete-tab", pos(docId), `--tab=${tab}`, "--force"];
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_docs_clear", {
@@ -36711,7 +37026,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, account }) => {
-    return runOrDiagnose(["docs", "clear", docId], { account });
+    return runOrDiagnose(["docs", "clear", pos(docId)], { account });
   });
   server.registerTool("gog_docs_insert_footnote", {
     description: "Insert a footnote at a character index (or end-of-doc) and populate its text. The footnote reference mark is placed in the body; the footnote content goes in the new footnote segment.",
@@ -36729,7 +37044,8 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, text, file: file2, index, atEnd, at, occurrence, matchCase, tab, account }) => {
-    const args = ["docs", "insert-footnote", docId];
+    if (file2) confinePath(file2, "file");
+    const args = ["docs", "insert-footnote", pos(docId)];
     if (text !== void 0) args.push(`--text=${text}`);
     if (file2) args.push(`--file=${file2}`);
     if (index !== void 0) args.push(`--index=${index}`);
@@ -36756,7 +37072,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, type, index, atEnd, at, occurrence, matchCase, tab, batch, account }) => {
-    const args = ["docs", "insert-section-break", docId];
+    const args = ["docs", "insert-section-break", pos(docId)];
     if (type) args.push(`--type=${type}`);
     if (index !== void 0) args.push(`--index=${index}`);
     if (atEnd) args.push("--at-end");
@@ -36782,7 +37098,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, index, atEnd, at, occurrence, matchCase, tab, batch, account }) => {
-    const args = ["docs", "insert-horizontal-rule", docId];
+    const args = ["docs", "insert-horizontal-rule", pos(docId)];
     if (index !== void 0) args.push(`--index=${index}`);
     if (atEnd) args.push("--at-end");
     if (at) args.push(`--at=${at}`);
@@ -36809,7 +37125,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, count, separator, index, atEnd, at, occurrence, matchCase, tab, batch, account }) => {
-    const args = ["docs", "section-columns", docId, `--count=${count}`];
+    const args = ["docs", "section-columns", pos(docId), `--count=${count}`];
     if (separator) args.push(`--separator=${separator}`);
     if (index !== void 0) args.push(`--index=${index}`);
     if (atEnd) args.push("--at-end");
@@ -36829,7 +37145,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, tab, account }) => {
-    const args = ["docs", "header", "list", docId];
+    const args = ["docs", "header", "list", pos(docId)];
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
   });
@@ -36849,7 +37165,8 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, text, file: file2, index, atEnd, at, occurrence, matchCase, tab, account }) => {
-    const args = ["docs", "header", "create", docId];
+    if (file2) confinePath(file2, "file");
+    const args = ["docs", "header", "create", pos(docId)];
     if (text !== void 0) args.push(`--text=${text}`);
     if (file2) args.push(`--file=${file2}`);
     if (index !== void 0) args.push(`--index=${index}`);
@@ -36870,7 +37187,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, headerId, tab, account }) => {
-    const args = ["docs", "header", "delete", docId, headerId];
+    const args = ["docs", "header", "delete", pos(docId), pos(headerId)];
     if (tab) args.push(`--tab=${tab}`);
     args.push("--force");
     return runOrDiagnose(args, { account });
@@ -36884,7 +37201,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, tab, account }) => {
-    const args = ["docs", "footer", "list", docId];
+    const args = ["docs", "footer", "list", pos(docId)];
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
   });
@@ -36904,7 +37221,8 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, text, file: file2, index, atEnd, at, occurrence, matchCase, tab, account }) => {
-    const args = ["docs", "footer", "create", docId];
+    if (file2) confinePath(file2, "file");
+    const args = ["docs", "footer", "create", pos(docId)];
     if (text !== void 0) args.push(`--text=${text}`);
     if (file2) args.push(`--file=${file2}`);
     if (index !== void 0) args.push(`--index=${index}`);
@@ -36925,7 +37243,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, footerId, tab, account }) => {
-    const args = ["docs", "footer", "delete", docId, footerId];
+    const args = ["docs", "footer", "delete", pos(docId), pos(footerId)];
     if (tab) args.push(`--tab=${tab}`);
     args.push("--force");
     return runOrDiagnose(args, { account });
@@ -36945,7 +37263,8 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, file: file2, url: url2, objectId, matchAlt, name, parent, tab, account }) => {
-    const args = ["docs", "replace-image", docId];
+    if (file2) confinePath(file2, "file");
+    const args = ["docs", "replace-image", pos(docId)];
     if (file2) args.push(`--file=${file2}`);
     if (url2) args.push(`--url=${url2}`);
     if (objectId) args.push(`--object-id=${objectId}`);
@@ -36967,7 +37286,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, rows, table, tab, account }) => {
-    const args = ["docs", "table-row", "pin-header", docId, `--rows=${rows}`];
+    const args = ["docs", "table-row", "pin-header", pos(docId), `--rows=${rows}`];
     if (table) args.push(`--table=${table}`);
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
@@ -36985,7 +37304,7 @@ function registerExtraDocsTools(server) {
       account: accountParam
     })
   }, async ({ docId, row, minHeight, preventOverflow, table, tab, account }) => {
-    const args = ["docs", "table-row", "style", docId];
+    const args = ["docs", "table-row", "style", pos(docId)];
     if (row !== void 0) args.push(`--row=${row}`);
     if (minHeight) args.push(`--min-height=${minHeight}`);
     if (preventOverflow !== void 0) args.push(preventOverflow ? "--prevent-overflow" : "--no-prevent-overflow");