gogcli-mcp-contacts 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,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 accountParam = external_exports.string().optional().describe(
   "Google account email to use, e.g. you@gmail.com \u2014 must be the full address, not a bare username. Overrides the GOG_ACCOUNT env var. Omit to use the single configured account."
@@ -35114,9 +35391,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")
@@ -35130,7 +35415,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) {
@@ -35252,6 +35551,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.";
@@ -35309,7 +35609,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,
@@ -35329,7 +35629,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) {
@@ -35356,7 +35656,7 @@ function registerAuthToolsWith(server, defaultServices) {
       const args = [
         "auth",
         "add",
-        email3,
+        pos(email3),
         "--remote",
         "--step",
         "2",
@@ -35376,6 +35676,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."
   });
 }
@@ -35423,7 +35724,7 @@ function registerContactsTools(server) {
       account: accountParam
     })
   }, async ({ query, account }) => {
-    return runOrDiagnose(["contacts", "search", query], { account });
+    return runOrDiagnose(["contacts", "search", pos(query)], { account });
   });
   server.registerTool("gog_contacts_list", {
     description: "List all Google Contacts.",
@@ -35442,7 +35743,7 @@ function registerContactsTools(server) {
       account: accountParam
     })
   }, async ({ resourceName, account }) => {
-    return runOrDiagnose(["contacts", "get", resourceName], { account });
+    return runOrDiagnose(["contacts", "get", pos(resourceName)], { account });
   });
   server.registerTool("gog_contacts_create", {
     description: "Create a new Google Contact.",
@@ -35480,7 +35781,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."),
@@ -35501,10 +35802,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.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) => {
@@ -35541,8 +35842,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";
@@ -35594,7 +35895,7 @@ function registerExtraContactsTools(server) {
       account: accountParam
     })
   }, async ({ userId, account }) => {
-    return runOrDiagnose(["people", "get", userId], { account });
+    return runOrDiagnose(["people", "get", pos(userId)], { account });
   });
   server.registerTool("gog_people_search", {
     description: "Search the Google Workspace directory (covers internal users, unlike contacts search which is limited to your personal contacts).",
@@ -35608,7 +35909,7 @@ function registerExtraContactsTools(server) {
       account: accountParam
     })
   }, async ({ query, max, pageToken, page, all, account }) => {
-    const args = ["people", "search", query];
+    const args = ["people", "search", pos(query)];
     if (max !== void 0) args.push(`--max=${max}`);
     const token = resolvePageToken({ pageToken, page });
     if (token) args.push(`--page=${token}`);
@@ -35625,7 +35926,7 @@ function registerExtraContactsTools(server) {
     })
   }, async ({ userId, type, account }) => {
     const args = ["people", "relations"];
-    if (userId) args.push(userId);
+    if (userId) args.push(pos(userId));
     if (type) args.push(`--type=${type}`);
     return runOrDiagnose(args, { account });
   });
@@ -35648,7 +35949,7 @@ function registerExtraContactsTools(server) {
       account: accountParam
     })
   }, async ({ resourceName, given, family, email: email3, phone, org, title, url: url2, note, address, birthday, ignoreEtag, account }) => {
-    const args = ["contacts", "update", resourceName];
+    const args = ["contacts", "update", pos(resourceName)];
     if (given !== void 0) args.push(`--given=${given}`);
     if (family !== void 0) args.push(`--family=${family}`);
     if (email3 !== void 0) args.push(`--email=${email3}`);
@@ -35670,11 +35971,12 @@ function registerExtraContactsTools(server) {
       account: accountParam
     })
   }, async ({ resourceName, account }) => {
-    return runOrDiagnose(["contacts", "delete", resourceName, "--force"], { account });
+    return runOrDiagnose(["contacts", "delete", pos(resourceName), "--force"], { account });
   });
   server.registerTool("gog_contacts_export", {
     description: "Export contacts as vCard (.vcf). Provide a selector (resource name, email, or name), or use query / all to export multiple.",
-    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({
       selector: external_exports.string().optional().describe("Contact resource name (people/...), email, or name"),
       query: external_exports.string().optional().describe("Search query to export (max 30 results)"),
@@ -35686,8 +35988,9 @@ function registerExtraContactsTools(server) {
       account: accountParam
     })
   }, async ({ selector, query, all, out, max, pageToken, page, account }) => {
+    if (out) confinePath(out, "out", { allowDash: true });
     const args = ["contacts", "export"];
-    if (selector) args.push(selector);
+    if (selector) args.push(pos(selector));
     if (query) args.push(`--query=${query}`);
     if (all) args.push("--all");
     if (out) args.push(`--out=${out}`);
@@ -35762,7 +36065,7 @@ function registerExtraContactsTools(server) {
       account: accountParam
     })
   }, async ({ query, max, account }) => {
-    const args = ["contacts", "other", "search", query];
+    const args = ["contacts", "other", "search", pos(query)];
     if (max !== void 0) args.push(`--max=${max}`);
     return runOrDiagnose(args, { account });
   });
@@ -35776,7 +36079,7 @@ function registerExtraContactsTools(server) {
       account: accountParam
     })
   }, async ({ userId, personFields, pretty, account }) => {
-    const args = ["people", "raw", userId];
+    const args = ["people", "raw", pos(userId)];
     if (personFields) args.push(`--person-fields=${personFields}`);
     if (pretty) args.push("--pretty");
     return runOrDiagnose(args, { account, lossless: true });

package/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-contacts",
-  "version": "4.2.5",
+  "version": "4.3.0",
   "mcpName": "io.github.chrischall/gogcli-mcp-contacts",
   "description": "Extended Google Contacts + People MCP server via gogcli — auth + Contacts + Workspace directory (People API)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -24,7 +24,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.1.0",
+    "@chrischall/mcp-utils": "^2.4.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.6.1"
   },

package/src/tools/contacts-extra.ts

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose, pageTokenParam, pageAliasParam, resolvePageToken} from '../../../gogcli-mcp/src/lib.js';
+import { accountParam, runOrDiagnose, pageTokenParam, pageAliasParam, resolvePageToken, pos, confinePath } from '../../../gogcli-mcp/src/lib.js';
+import type { GogArg } from '../../../gogcli-mcp/src/lib.js';
 
 // People is the richer API behind Google Contacts: Workspace directory
 // search, profile fields, and relations.
@@ -23,7 +24,7 @@ export function registerExtraContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ userId, account }) => {
-    return runOrDiagnose(['people', 'get', userId], { account });
+    return runOrDiagnose(['people', 'get', pos(userId)], { account });
   });
 
   server.registerTool('gog_people_search', {
@@ -38,7 +39,7 @@ export function registerExtraContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ query, max, pageToken, page, all, account }) => {
-    const args = ['people', 'search', query];
+    const args: GogArg[] = ['people', 'search', pos(query)];
     if (max !== undefined) args.push(`--max=${max}`);
     const token = resolvePageToken({ pageToken, page });
     if (token) args.push(`--page=${token}`);
@@ -55,8 +56,8 @@ export function registerExtraContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ userId, type, account }) => {
-    const args = ['people', 'relations'];
-    if (userId) args.push(userId);
+    const args: GogArg[] = ['people', 'relations'];
+    if (userId) args.push(pos(userId));
     if (type) args.push(`--type=${type}`);
     return runOrDiagnose(args, { account });
   });
@@ -80,7 +81,7 @@ export function registerExtraContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ resourceName, given, family, email, phone, org, title, url, note, address, birthday, ignoreEtag, account }) => {
-    const args = ['contacts', 'update', resourceName];
+    const args: GogArg[] = ['contacts', 'update', pos(resourceName)];
     if (given !== undefined) args.push(`--given=${given}`);
     if (family !== undefined) args.push(`--family=${family}`);
     if (email !== undefined) args.push(`--email=${email}`);
@@ -103,12 +104,13 @@ export function registerExtraContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ resourceName, account }) => {
-    return runOrDiagnose(['contacts', 'delete', resourceName, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
+    return runOrDiagnose(['contacts', 'delete', pos(resourceName), '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_contacts_export', {
     description: 'Export contacts as vCard (.vcf). Provide a selector (resource name, email, or name), or use query / all to export multiple.',
-    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: z.object({
       selector: z.string().optional().describe('Contact resource name (people/...), email, or name'),
       query: z.string().optional().describe('Search query to export (max 30 results)'),
@@ -120,8 +122,9 @@ export function registerExtraContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ selector, query, all, out, max, pageToken, page, account }) => {
-    const args = ['contacts', 'export'];
-    if (selector) args.push(selector);
+    if (out) confinePath(out, 'out', { allowDash: true });
+    const args: GogArg[] = ['contacts', 'export'];
+    if (selector) args.push(pos(selector));
     if (query) args.push(`--query=${query}`);
     if (all) args.push('--all');
     if (out) args.push(`--out=${out}`);
@@ -143,7 +146,7 @@ export function registerExtraContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ match, max, resource, apply, failEmpty, account }) => {
-    const args = ['contacts', 'dedupe'];
+    const args: GogArg[] = ['contacts', 'dedupe'];
     if (match) args.push(`--match=${match}`);
     if (max !== undefined) args.push(`--max=${max}`);
     if (resource) for (const r of resource) args.push(`--resource=${r}`);
@@ -164,7 +167,7 @@ export function registerExtraContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ max, pageToken, page, all, account }) => {
-    const args = ['contacts', 'directory', 'list'];
+    const args: GogArg[] = ['contacts', 'directory', 'list'];
     if (max !== undefined) args.push(`--max=${max}`);
     const token = resolvePageToken({ pageToken, page });
     if (token) args.push(`--page=${token}`);
@@ -183,7 +186,7 @@ export function registerExtraContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ max, pageToken, page, all, account }) => {
-    const args = ['contacts', 'other', 'list'];
+    const args: GogArg[] = ['contacts', 'other', 'list'];
     if (max !== undefined) args.push(`--max=${max}`);
     const token = resolvePageToken({ pageToken, page });
     if (token) args.push(`--page=${token}`);
@@ -200,7 +203,7 @@ export function registerExtraContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ query, max, account }) => {
-    const args = ['contacts', 'other', 'search', query];
+    const args: GogArg[] = ['contacts', 'other', 'search', pos(query)];
     if (max !== undefined) args.push(`--max=${max}`);
     return runOrDiagnose(args, { account });
   });
@@ -215,7 +218,7 @@ export function registerExtraContactsTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ userId, personFields, pretty, account }) => {
-    const args = ['people', 'raw', userId];
+    const args: GogArg[] = ['people', 'raw', pos(userId)];
     if (personFields) args.push(`--person-fields=${personFields}`);
     if (pretty) args.push('--pretty');
     // Verbatim by contract: see the `lossless` note on runOrDiagnose.

package/tests/tools/contacts-extra.test.ts

@@ -3,6 +3,7 @@ import { registerExtraContactsTools } from '../../src/tools/contacts-extra.js';
 import * as lib from '../../../gogcli-mcp/src/lib.js';
 import { createTestHarness, type TestHarness } from '@chrischall/mcp-utils/test';
 import { rawTextResult } from '@chrischall/mcp-utils';
+import { pos } from '../../../gogcli-mcp/src/argv.js';
 
 vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
   const actual = await importOriginal<typeof lib>();
@@ -35,27 +36,27 @@ describe('gog_people_me', () => {
 describe('gog_people_get', () => {
   it('calls runOrDiagnose with userId', async () => {
     await harness.callTool('gog_people_get', { userId: 'people/c123' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'get', 'people/c123'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'get', pos('people/c123')], { account: undefined });
   });
 });
 
 describe('gog_people_search', () => {
   it('calls runOrDiagnose with query', async () => {
     await harness.callTool('gog_people_search', { query: 'alice' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'search', 'alice'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'search', pos('alice')], { account: undefined });
   });
 
   it('passes pagination flags', async () => {
     await harness.callTool('gog_people_search', { query: 'alice', max: 100, page: 'tok', all: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['people', 'search', 'alice', '--max=100', '--page=tok', '--all'],
+      ['people', 'search', pos('alice'), '--max=100', '--page=tok', '--all'],
       { account: undefined },
     );
   });
 
   it('omits --all when false', async () => {
     await harness.callTool('gog_people_search', { query: 'x', all: false });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'search', 'x'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'search', pos('x')], { account: undefined });
   });
 });
 
@@ -68,7 +69,7 @@ describe('gog_people_relations', () => {
   it('passes userId and --type when provided', async () => {
     await harness.callTool('gog_people_relations', { userId: 'people/c123', type: 'manager' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['people', 'relations', 'people/c123', '--type=manager'],
+      ['people', 'relations', pos('people/c123'), '--type=manager'],
       { account: undefined },
     );
   });
@@ -77,7 +78,7 @@ describe('gog_people_relations', () => {
 describe('gog_contacts_update', () => {
   it('calls runOrDiagnose with just resourceName', async () => {
     await harness.callTool('gog_contacts_update', { resourceName: 'people/c1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'update', 'people/c1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'update', pos('people/c1')], { account: undefined });
   });
 
   it('passes all fields including empty-string clears', async () => {
@@ -97,7 +98,7 @@ describe('gog_contacts_update', () => {
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
       [
-        'contacts', 'update', 'people/c1',
+        'contacts', 'update', pos('people/c1'),
         '--given=Ada', '--family=Lovelace', '--email=', '--phone=+1',
         '--org=Analytical', '--title=Engineer', '--url=https://a.com',
         '--note=hi', '--address=1 St;City', '--birthday=1815-12-10', '--ignore-etag',
@@ -108,14 +109,14 @@ describe('gog_contacts_update', () => {
 
   it('omits --ignore-etag when false', async () => {
     await harness.callTool('gog_contacts_update', { resourceName: 'people/c1', ignoreEtag: false });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'update', 'people/c1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'update', pos('people/c1')], { account: undefined });
   });
 });
 
 describe('gog_contacts_delete', () => {
   it('calls runOrDiagnose with resourceName', async () => {
     await harness.callTool('gog_contacts_delete', { resourceName: 'people/c1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'delete', 'people/c1', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'delete', pos('people/c1'), '--force'], { account: undefined });
   });
 });
 
@@ -135,7 +136,7 @@ describe('gog_contacts_export', () => {
       page: 'tok',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['contacts', 'export', 'people/c1', '--query=ada', '--all', '--out=out.vcf', '--max=10', '--page=tok'],
+      ['contacts', 'export', pos('people/c1'), '--query=ada', '--all', '--out=out.vcf', '--max=10', '--page=tok'],
       { account: undefined },
     );
   });
@@ -221,13 +222,13 @@ describe('gog_contacts_other_list', () => {
 describe('gog_contacts_other_search', () => {
   it('calls runOrDiagnose with query', async () => {
     await harness.callTool('gog_contacts_other_search', { query: 'ada' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'other', 'search', 'ada'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'other', 'search', pos('ada')], { account: undefined });
   });
 
   it('passes --max when provided', async () => {
     await harness.callTool('gog_contacts_other_search', { query: 'ada', max: 25 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['contacts', 'other', 'search', 'ada', '--max=25'],
+      ['contacts', 'other', 'search', pos('ada'), '--max=25'],
       { account: undefined },
     );
   });
@@ -236,7 +237,7 @@ describe('gog_contacts_other_search', () => {
 describe('gog_people_raw', () => {
   it('calls runOrDiagnose with userId', async () => {
     await harness.callTool('gog_people_raw', { userId: 'people/c123' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'raw', 'people/c123'], { account: undefined, lossless: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'raw', pos('people/c123')], { account: undefined, lossless: true });
   });
 
   it('passes --person-fields and --pretty when provided', async () => {
@@ -246,13 +247,55 @@ describe('gog_people_raw', () => {
       pretty: true,
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['people', 'raw', 'people/c123', '--person-fields=names,emailAddresses', '--pretty'],
+      ['people', 'raw', pos('people/c123'), '--person-fields=names,emailAddresses', '--pretty'],
       { account: undefined, lossless: true },
     );
   });
 
   it('omits --pretty when false', async () => {
     await harness.callTool('gog_people_raw', { userId: 'people/c123', pretty: false });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'raw', 'people/c123'], { account: undefined, lossless: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'raw', pos('people/c123')], { account: undefined, lossless: true });
+  });
+});
+
+// SEC-3/SEC-4: every model-supplied server path must resolve inside an
+// operator-configured root (GOG_FILE_ROOTS). The suite runs with '/' so the
+// arg-shape tests can use any path; these narrow it.
+async function withFileRoots<T>(roots: string, fn: () => Promise<T>): Promise<T> {
+  const prev = process.env.GOG_FILE_ROOTS;
+  process.env.GOG_FILE_ROOTS = roots;
+  try {
+    return await fn();
+  } finally {
+    process.env.GOG_FILE_ROOTS = prev;
+  }
+}
+
+describe('server paths are confined to GOG_FILE_ROOTS', () => {
+  it.each([
+    ['gog_contacts_export', {"out": "/Users/me/.zshrc"}, 'out'],
+  ] as Array<[string, Record<string, unknown>, string]>)('%s refuses %j outside the roots', async (tool, args, param) => {
+    const h = harness;
+    const result = await withFileRoots('/srv/gog-files', () => h.callTool(tool, args));
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(new RegExp(`${param} ".*" is outside the directories`));
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+
+  // Clients auto-approve readOnlyHint tools; these write (and can overwrite)
+  // files on the gog host, so they must not claim to be read-only.
+  it.each(["gog_contacts_export"])('%s is not advertised as read-only and is marked destructive', async (name) => {
+    const h = harness;
+    const { tools } = await h.client.listTools();
+    const tool = tools.find((t) => t.name === name)!;
+    expect(tool.annotations?.readOnlyHint).not.toBe(true);
+    expect(tool.annotations?.destructiveHint).toBe(true);
+  });
+});
+
+describe('gog_contacts_export — stdout', () => {
+  it('still accepts "-" (stdout) whatever the roots', async () => {
+    await withFileRoots('/srv/gog-files', () => harness.callTool('gog_contacts_export', { out: '-' }));
+    expect(lib.runOrDiagnose).toHaveBeenCalled();
   });
 });

package/vitest.config.ts

@@ -2,6 +2,11 @@ import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
   test: {
+    // The arg-shape tests pass arbitrary server paths; confinement is exercised
+    // explicitly by the tests that narrow GOG_FILE_ROOTS themselves.
+    env: {
+      GOG_FILE_ROOTS: '/',
+    },
     coverage: {
       provider: 'v8',
       include: ['src/**/*.ts'],