mcp-google-multi 6.0.1 → 6.1.0-beta.1

package/dist/tools/gmail.js

@@ -5,18 +5,25 @@ import { accountArgLive } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError, invalidParams, mapGoogleError } from './_errors.js';
 import { buildReplyHeaders, composeRaw, renderMarkdown, htmlToMarkdown, HeaderInjectionError } from './gmail-mime.js';
-import { hostFilesRefused, prepareLocalDest } from './_local-files.js';
-import { checkOutbound } from '../outbound-allowlist.js';
+import { hostFilesRefused, prepareLocalDest, cleanupPartialWrite, assertLocalPathAllowed, localFileErrorResult, LocalFileError } from './_local-files.js';
+import { checkOutbound, outboundDeniedEnvelope, resolveOutboundAllowlist } from '../outbound-allowlist.js';
 import addressparser from 'nodemailer/lib/addressparser/index.js';
 import { lookup as lookupMime } from 'mime-types';
-import { configDir } from '../config-file.js';
-import { getTokenDir } from '../accounts.js';
 import { sliceClean } from '../trim.js';
 import * as path from 'path';
 import * as fs from 'fs';
 function getHeader(headers, name) {
     return headers?.find((h) => h.name?.toLowerCase() === name.toLowerCase())?.value ?? '';
 }
+// RFC 5322 permits a header field to repeat; most generators comma-join
+// recipients into a single To/Cc/Bcc line, but a raw, hand-built message
+// (e.g. one substituted in via gmail.users.drafts.update, which the
+// outbound allowlist cannot otherwise inspect) could carry a SECOND To/Cc/
+// Bcc line instead. getHeader's .find only ever sees the first match, so a
+// recipient check built on it alone would miss every repeat.
+function getHeaderAll(headers, name) {
+    return (headers ?? []).filter((h) => h.name?.toLowerCase() === name.toLowerCase()).map((h) => h.value ?? '');
+}
 function pickHeaders(headers, names) {
     const out = {};
     for (const name of names)
@@ -207,7 +214,7 @@ const GMAIL_MAX_MESSAGE_BYTES = 25 * 1024 * 1024;
 const estimateEncoded = (rawBytes) => Math.ceil((rawBytes * 4) / 3);
 const attachmentSchema = z
     .array(z.object({
-    path: z.string().describe('Absolute local path to the file to attach'),
+    path: z.string().describe('Path to the file to attach, on the machine running the server: confined to GOOGLE_LOCAL_FILES_DIR (default <home>/Downloads/mcp-google-multi); a relative path resolves inside it, an absolute path must already be inside it.'),
     filename: z.string().optional().describe('MIME filename; defaults to the path basename'),
     contentType: z.string().optional().describe('MIME type; defaults to a lookup on the filename'),
 }))
@@ -215,55 +222,27 @@ const attachmentSchema = z
     .describe('Files to attach (each { path, filename?, contentType? }); path must be absolute');
 /** Reads attachment files into buffers (THIS server reads them, never
  * MailComposer), enforces absolute-path + total-size guards, and derives the
- * MIME filename via basename so a caller name can't inject path separators. */
-// Deny reading inside the server's own secret dirs; mailing out master.key /
-// <alias>.enc / mcp-jwt.key would be account takeover (also guards against a prompt-injected attach path).
-function isInside(dir, target) {
-    let d = path.resolve(dir);
-    let t = path.resolve(target);
-    // Windows path comparison is case-insensitive; without folding, a
-    // drive-letter/casing difference makes path.relative report "outside".
-    if (process.platform === 'win32') {
-        d = d.toLowerCase();
-        t = t.toLowerCase();
-    }
-    const rel = path.relative(d, t);
-    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
-}
-/** Deny if realTarget resolves inside `dir` (both realpath'd so a symlinked
- * dir or 8.3/extended-prefix form can't slip past). */
-async function isInsideRealDir(dir, realTarget) {
-    let realDir;
-    try {
-        realDir = await fs.promises.realpath(dir);
-    }
-    catch {
-        return false; // dir does not exist → target cannot be inside it
-    }
-    return isInside(realDir, realTarget);
-}
+ * MIME filename via basename so a caller name can't inject path separators.
+ * The absolute-path + config/token-dir confinement rule itself lives in
+ * assertLocalPathAllowed (src/tools/_local-files.ts), shared with Drive's
+ * upload/update/download/export so the two surfaces cannot drift apart. */
 export async function readAttachments(raw, bodyBytes) {
     if (!raw || raw.length === 0)
         return undefined;
-    const denied = [configDir(), getTokenDir()];
     const out = [];
     let total = bodyBytes;
     for (const a of raw) {
-        if (!path.isAbsolute(a.path)) {
-            throw new GmailComposeError('validation_error', `attachment path must be absolute: ${path.basename(a.path)}`);
-        }
-        // Resolve symlinks BEFORE any confinement check, or a symlink defeats it.
+        // Resolve symlinks BEFORE any confinement check (inside the helper), or a
+        // symlink defeats it; read the resolved real path, not the caller's.
         let real;
         try {
-            real = await fs.promises.realpath(a.path);
+            real = await assertLocalPathAllowed(a.path, 'read');
         }
-        catch {
-            throw new GmailComposeError('E_ATTACHMENT_NOT_FOUND', `attachment not found or unreadable: ${path.basename(a.path)}`);
-        }
-        for (const d of denied) {
-            if (await isInsideRealDir(d, real)) {
-                throw new GmailComposeError('E_ATTACHMENT_FORBIDDEN', `refusing to attach a file inside the server's config/token directory: ${path.basename(a.path)}`);
+        catch (err) {
+            if (err instanceof LocalFileError) {
+                throw new GmailComposeError('E_ATTACHMENT_FORBIDDEN', `refusing to attach this file (outside the allowed local-files root, or inside the server's config/token directory): ${path.basename(a.path)}`);
             }
+            throw new GmailComposeError('E_ATTACHMENT_NOT_FOUND', `attachment not found or unreadable: ${path.basename(a.path)}`);
         }
         // stat BEFORE read: reject non-regular files (a FIFO would block readFile
         // forever) and over-cap files without buffering them.
@@ -766,7 +745,7 @@ export function registerGmailTools(server, deps = {}) {
             messageId: z.string().min(1).describe('The Gmail message ID'),
             attachmentId: z.string().min(1).describe('The attachment ID from gmail_read response'),
             filename: z.string().describe('Filename to save as (e.g. report.xlsx)'),
-            savePath: z.string().min(1).describe('Absolute DIRECTORY path to save into (created if missing, on the machine running the server), e.g. /home/user/Downloads; the file name comes from `filename`'),
+            savePath: z.string().min(1).describe('Destination folder to save into, on the machine running the server: confined to GOOGLE_LOCAL_FILES_DIR (default <home>/Downloads/mcp-google-multi), created if missing; a relative path resolves inside it, an absolute path must already be inside it. The file name comes from `filename`.'),
         },
     }, async ({ account, messageId, attachmentId, filename, savePath }) => {
         try {
@@ -781,13 +760,28 @@ export function registerGmailTools(server, deps = {}) {
             if (!data)
                 throw new Error('No attachment data returned');
             const buffer = Buffer.from(data, 'base64url');
-            const fullPath = prepareLocalDest(savePath, filename);
-            await fs.promises.writeFile(fullPath, buffer, { mode: 0o600 });
+            const fullPath = await prepareLocalDest(savePath, filename);
+            try {
+                // wx: never silently clobber; prepareLocalDest already checked
+                // existence, this is the belt-and-suspenders race guard.
+                await fs.promises.writeFile(fullPath, buffer, { mode: 0o600, flag: 'wx' });
+            }
+            catch (err) {
+                // A failed download must not leave a partial file behind blocking
+                // a retry with local_path_exists; best-effort, original error wins.
+                // EEXIST means wx itself refused to open: the TOCTOU race lost to
+                // another call that already owns fullPath, so this call never
+                // wrote anything there and must not delete that other call's file.
+                await cleanupPartialWrite(fullPath, err);
+                throw err;
+            }
             return {
                 content: [{ type: 'text', text: `Saved to ${fullPath} (${buffer.length} bytes)` }],
             };
         }
         catch (error) {
+            if (error instanceof LocalFileError)
+                return localFileErrorResult(error, account);
             const mapped = composeErrorResult(error, account);
             return mapped ?? handleGmailError(error, account);
         }
@@ -1057,6 +1051,30 @@ export function registerGmailTools(server, deps = {}) {
         try {
             const auth = await getClientFn(account);
             const gmail = gmailClient({ version: 'v1', auth });
+            // A draft is only ever recipient-checked when it is composed
+            // (gmail_create_draft). Its raw content can be replaced afterward
+            // through google_api_call (gmail.users.drafts.update), which the
+            // allowlist cannot inspect (raw base64 RFC 822) and so refuses
+            // outright; this re-checks the draft's actual To/Cc/Bcc right
+            // before send so that chain, or any other way a draft's content
+            // changed after creation, cannot slip an unlisted recipient through.
+            if (resolveOutboundAllowlist()) {
+                // drafts.get has no metadataHeaders param (unlike messages.get);
+                // format: 'full' is the only format guaranteed to include headers.
+                const draft = await gmail.users.drafts.get({
+                    userId: 'me',
+                    id: draftId,
+                    format: 'full',
+                });
+                const headers = draft.data.message?.payload?.headers ?? [];
+                const recipients = ['To', 'Cc', 'Bcc']
+                    .flatMap((name) => getHeaderAll(headers, name))
+                    .flatMap((value) => parseAddresses(value))
+                    .map((a) => a.address);
+                const outbound = checkOutbound('gmail_send_draft recipient', recipients, account);
+                if (outbound)
+                    return outbound;
+            }
             const res = await gmail.users.drafts.send({
                 userId: 'me',
                 requestBody: { id: draftId },
@@ -1240,6 +1258,12 @@ export function registerGmailTools(server, deps = {}) {
             restrictToDomain: coerceBoolean.optional().describe('Only reply to same domain (default: false)'),
         },
     }, async ({ account, enableAutoReply, responseSubject, responseBodyPlainText, startTime, endTime, restrictToContacts, restrictToDomain }) => {
+        // An unrestricted auto-reply answers every incoming sender, not just
+        // allowlisted ones, so enabling it without either restriction is
+        // refused outright while the allowlist is active.
+        if (enableAutoReply && !restrictToContacts && !restrictToDomain && resolveOutboundAllowlist()) {
+            return outboundDeniedEnvelope('gmail_set_vacation auto-reply', ['(every sender, not just allowlisted ones; set restrictToContacts or restrictToDomain)'], String(account));
+        }
         try {
             const auth = await getClientFn(account);
             const gmail = gmailClient({ version: 'v1', auth });

package/dist/tools/google-api.d.ts

@@ -1,5 +1,5 @@
 import type { ToolRegistry } from '../registry.js';
-import { type Policy } from '../write-control.js';
+import type { Policy } from '../write-control.js';
 import { type Toolsets } from '../toolsets.js';
 import { type ExecuteDeps } from '../executor.js';
 import { type DiscoveryDeps, type DiscoveryMethod } from '../discovery-client.js';
@@ -9,4 +9,21 @@ export interface EscapeDeps extends DiscoveryDeps, ExecuteDeps {
 /** Up to three closest known ids for the unknown_method did-you-mean hint;
  * bounded distance so unrelated ids never masquerade as suggestions. */
 export declare function nearestMethodIds(methodId: string, index: DiscoveryMethod[]): string[];
+export declare const EXTRA_METHOD_TOOLS: Record<string, string[]>;
+export interface EscapeHatchNames {
+    /** Every name a deny glob is checked against: every curated tool name
+     * sharing this method, its generated twin, the full method-path name,
+     * the legacy last-segment name. Denying any one of them can only narrow
+     * what gets through, never widen it, so listing every curated tool here
+     * (even when several share one raw method) is always safe. The escape
+     * hatch has no allow-list of its own anymore (write-control.ts); only
+     * full-writes auto-allows, everything else asks a human. */
+    deny: string[];
+    /** The real tool name when exactly one exists (curated or generated),
+     * else the full-path name: shown in the human confirmation prompt and
+     * used to build a sensible message when this call is denied outright. */
+    primary: string;
+}
+/** Every name write-control might reasonably know this operation by. */
+export declare function escapeHatchNames(policyService: string, methodId: string): EscapeHatchNames;
 export declare function registerEscapeTools(registry: ToolRegistry, policy: Policy, deps?: EscapeDeps): void;

package/dist/tools/google-api.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { isAllowed, writeDisabledResult } from '../write-control.js';
+import { escapeHatchGate } from './_escape-hatch.js';
 import { accountArgLive } from '../accounts.js';
 import { getClient } from '../client.js';
 import { coerceJson } from './_coerce.js';
@@ -8,6 +8,7 @@ import { editDistance, SUGGEST_MAX_INPUT } from '../scope-catalog.js';
 import { executeApiMethod, jsonResult } from '../executor.js';
 import { SUPPORTED_APIS, resolveApiAliases, cudFromMethod, loadMethodIndex, searchMethods, MAX_SEARCH_QUERY, } from '../discovery-client.js';
 import { hints } from '../hint-provider.js';
+import { CURATED_METHOD_TOOLS, GENERATED_METHOD_TOOLS, CUD_OVERRIDES } from './generated/method-map.js';
 // Policy/toolset namespace for each API alias must match the NAMED tools' service
 // names, or user deny globs and GOOGLE_TOOLSETS silently miss escape-hatch calls.
 const SERVICE_FOR_ALIAS = {
@@ -52,6 +53,38 @@ export function nearestMethodIds(methodId, index) {
         .slice(0, 3)
         .map((x) => x.id);
 }
+// Mirrors scripts/gen-tools.ts's snakeCase: src/ and scripts/ are separate
+// compilation roots (see tsconfig.scripts.json), so the convention is
+// duplicated rather than imported. A drift between the two would only widen
+// the escape hatch's own full-path name, never narrow it: escapeHatchNames
+// below also carries the last-segment and real-tool names, so write-control
+// degrades gracefully, and the parity test below would catch a drift anyway.
+function snakeSegment(segment) {
+    return segment.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+}
+// A handful of Discovery methods that DO have their own generated twin
+// (so they are not in CURATED_METHOD_TOOLS, which only covers methods a
+// curated tool implements in place of generating one) are ALSO called, as
+// a secondary step, by an unrelated curated tool: e.g. sheets_copy_sheet_to
+// also calls sheets.spreadsheets.sheets.copyTo, the same method its own
+// generated twin sheets_spreadsheets_sheets_copy_to wraps. Listed here so a
+// deny written against that curated tool's name reaches the escape hatch
+// for this method too, not just its generated twin's name.
+export const EXTRA_METHOD_TOOLS = {
+    'sheets.spreadsheets.sheets.copyTo': ['sheets_copy_sheet_to'],
+};
+/** Every name write-control might reasonably know this operation by. */
+export function escapeHatchNames(policyService, methodId) {
+    const curatedNames = CURATED_METHOD_TOOLS[methodId] ?? EXTRA_METHOD_TOOLS[methodId] ?? [];
+    const generatedName = GENERATED_METHOD_TOOLS[methodId];
+    const tail = methodId.split('.').slice(1);
+    const fullPathName = tail.length > 0 ? `${policyService}_${tail.map(snakeSegment).join('_')}` : undefined;
+    const lastSegment = methodId.split('.').pop() ?? methodId;
+    const lastSegmentName = `${policyService}_${snakeSegment(lastSegment)}`;
+    const deny = [...new Set([...curatedNames, ...(generatedName ? [generatedName] : []), ...(fullPathName ? [fullPathName] : []), lastSegmentName])];
+    const primary = curatedNames.length === 1 ? curatedNames[0] : generatedName ?? fullPathName ?? lastSegmentName;
+    return { deny, primary };
+}
 function describeMethod(m) {
     return {
         api: m.api,
@@ -60,7 +93,7 @@ function describeMethod(m) {
         path: m.path,
         description: m.description,
         requiredParams: m.requiredParams,
-        cud: cudFromMethod(m),
+        cud: CUD_OVERRIDES[m.id] ?? cudFromMethod(m),
     };
 }
 export function registerEscapeTools(registry, policy, deps = {}) {
@@ -133,9 +166,11 @@ export function registerEscapeTools(registry, policy, deps = {}) {
     });
     registry.registerMeta('google_api_call', {
         description: 'Invoke any Google Workspace REST method by Discovery id (escape hatch for operations without a ' +
-            'dedicated tool). Find methods with google_api_search first. Subject to the same write-control ' +
-            'policy as named tools. On reads, pass a `fields` query param (Google partial response) to keep ' +
-            'the payload small. Returns JSON only — for binary/file content (media downloads, ' +
+            'dedicated tool). Find methods with google_api_search first. A write asks the connected human to ' +
+            'confirm the real call (account, verb, params, a destinations-first body summary) unless ' +
+            'GOOGLE_PROFILE=full-writes with no outbound allowlist; GOOGLE_READ_ONLY or a matching ' +
+            'GOOGLE_WRITE_DENY still refuse outright. On reads, pass a `fields` query param (Google partial ' +
+            'response) to keep the payload small. Returns JSON only; for binary/file content (media downloads, ' +
             'drive.files.export) use drive_download / drive_export instead.',
         inputSchema: {
             account: accountEnum.describe('Google account alias (omit for the default account)'),
@@ -199,16 +234,55 @@ export function registerEscapeTools(registry, policy, deps = {}) {
                 account,
             }, true);
         }
+        // ROUND 7 (MEDIUM 3): an undeclared pathParams key has no effect on
+        // the actual call (expandPath only substitutes {placeholders} the
+        // method's own path template names), but it was still echoed into
+        // the confirmation prompt verbatim, letting a caller stuff fake
+        // prompt text into a key the method never asked for. Rejected
+        // outright rather than silently ignored.
+        const declaredPathParams = new Set(Object.entries(method.params).filter(([, p]) => p.location === 'path').map(([n]) => n));
+        const unknownPathParams = Object.keys(pathParams ?? {}).filter((k) => !declaredPathParams.has(k));
+        if (unknownPathParams.length > 0) {
+            return jsonResult({
+                error: 'invalid_params',
+                message: `${method.id} does not declare path param(s): ${unknownPathParams.join(', ')}.`,
+                hint: `Declared path params for ${method.id}: ${[...declaredPathParams].join(', ') || '(none)'}.`,
+                retriable: false,
+                account,
+            }, true);
+        }
         // The RESOLVED index id only, never the caller's methodId argument.
         registry.usageMetrics?.recordEscapeMethod(method.id);
-        const cud = cudFromMethod(method);
+        // CUD_OVERRIDES corrects the handful of methods HTTP-verb inference
+        // misreads (MEDIUM 4: the effect is an argument, not the method name,
+        // e.g. a ChromeOS device "action" that can remote-wipe it); a
+        // generated method's own twin applies the identical override at gen
+        // time (scripts/gen-tools.ts), so a GOOGLE_WRITE_DENY glob keyed on
+        // the real write class matches here exactly as it would there.
+        const cud = CUD_OVERRIDES[method.id] ?? cudFromMethod(method);
         const policyService = serviceForAlias(apiKey);
-        const lastSegment = method.id.split('.').pop() ?? method.id;
-        // The escape hatch self-gates, so it needs the same scope signal as the registry
-        // wrapper, or a privileged method would slip past safe-writes here while its generated twin is refused.
-        const toolRef = { name: `${policyService}_${lastSegment}`, service: policyService, cud, scopes: method.scopes };
-        if (cud !== 'read' && !isAllowed(toolRef, policy)) {
-            return writeDisabledResult(toolRef, policy, account);
+        // Checked under every name the operation can have (real tool(s), full
+        // method path, legacy last-segment) because a method whose id ends in
+        // a generic verb, such as drive.permissions.create or
+        // gmail.users.settings.filters.create, would otherwise lose its
+        // resource and collapse onto a generic drive_create / gmail_create
+        // that an operator's resource-scoped GOOGLE_WRITE_DENY could not tell
+        // apart from an ordinary write. Deny on any name wins outright;
+        // everything else that reaches here either auto-allows under
+        // full-writes or asks a human (see escapeHatchGate).
+        if (cud !== 'read') {
+            const names = escapeHatchNames(policyService, method.id);
+            const gate = await escapeHatchGate(registry, names.deny, names.primary, { service: policyService, cud, scopes: method.scopes }, policy, {
+                account: account,
+                accountEmail: registry.accountSet().configs[account]?.email,
+                methodId: method.id,
+                httpMethod: method.httpMethod,
+                pathParams: pathParams,
+                queryParams: queryParams,
+                body,
+            });
+            if (gate)
+                return gate;
         }
         return executeApiMethod(method, {
             account: account,

package/dist/usage-metrics.js

@@ -41,7 +41,7 @@ export const KNOWN_ERROR_SLUGS = new Set([
     'invalid_scope', 'network_error', 'not_found', 'rate_limited',
     'reauth_required', 'recipient_not_allowed', 'temporarily_unavailable', 'tenant_not_found', 'too_large', 'toolset_disabled', 'unknown_api',
     'unknown_argument', 'unknown_method', 'unsupported_grant_type', 'unsupported_type',
-    'untrusted_host', 'upstream_error', 'validation_error', 'write_disabled',
+    'untrusted_host', 'upstream_error', 'validation_error', 'write_declined', 'write_disabled', 'write_unsummarizable',
 ]);
 const RPC_CODES = new Set([-32700, -32600, -32601, -32603]);
 export function stateDir(env = process.env) {

package/dist/write-control.d.ts

@@ -7,17 +7,19 @@ export interface Policy {
     allow: string[];
     deny: string[];
     /**
-     * Reserved seam (HTTP posture is "annotations only"): the dispatch
-     * transport is threaded into the resolved policy for a future seam, but in v6 alpha it does NOT stiffen the
-     * profile or alter any `isAllowed` verdict. "Stricter on HTTP" is achieved
-     * entirely by the `anthropic/requiresUserInteraction` annotation on the
-     * irreversible set, emitted identically on both transports.
+     * The dispatch transport, threaded into the resolved policy. Never
+     * alters `isAllowed`'s verdict or the profile itself: a curated tool's
+     * allow/deny/profile gate is identical on both transports. It DOES
+     * alter the escape hatch's ask step (`ToolRegistry.elicitConfirmation`,
+     * `src/registry.ts`): over HTTP, a write that would otherwise ask a
+     * human is refused instead, since the stateless HTTP transport cannot
+     * deliver the mid-call confirmation request (see docs/internals.md).
      * Optional so existing Policy literals (codegen/tests) need no change;
      * resolvePolicy always populates it.
      */
     transport?: Transport;
 }
-interface ToolRef {
+export interface ToolRef {
     name: string;
     service: string;
     cud: Cud;
@@ -41,6 +43,29 @@ export type PrivilegeKind = 'push_registration' | 'privileged_scope';
  * Discovery, and a list of names would drift out of date silently. */
 export declare function privilegeOf(tool: ToolRef): PrivilegeKind | undefined;
 export declare function isAllowed(tool: ToolRef, policy: Policy): boolean;
+export type EscapeHatchDecision = 'allow' | 'deny' | 'ask';
+export interface EscapeHatchVerdict {
+    decision: EscapeHatchDecision;
+    /** The ref that explains the verdict: the specific name a deny glob
+     * matched, or `primaryName` for every other case. */
+    ref: ToolRef;
+}
+/**
+ * The escape hatch (google_api_call and every generated per-method tool)
+ * has no allow-list or privileged-write special case of its own anymore:
+ * an explicit deny on any name the operation is known by still wins
+ * (narrows what gets through, never widens it, so listing every curated
+ * tool sharing a raw method here is always safe); full-writes with the
+ * outbound allowlist off is the only automatic allow; everything else
+ * (the default profile, safe-writes, any allow list set, or full-writes
+ * with the allowlist on) asks a human via elicitation instead of
+ * resolving the question itself.
+ */
+export declare function escapeHatchVerdict(denyNames: readonly string[], base: {
+    service: string;
+    cud: Cud;
+    scopes?: readonly string[];
+}, primaryName: string, policy: Policy, outboundAllowlistActive: boolean): EscapeHatchVerdict;
 export type DenyReason = {
     rule: 'read_only';
 } | {
@@ -66,4 +91,3 @@ export declare function writeDisabledResult(tool: ToolRef, policy: Policy, accou
     isError: true;
 };
 export declare function describePolicy(policy: Policy): string;
-export {};

package/dist/write-control.js

@@ -68,8 +68,11 @@ function matchesAny(tool, globs) {
 // billing, or deployed code: not a "safe" write, whatever its HTTP verb.
 const PRIVILEGED_SCOPE_RE = /\/auth\/(admin\.directory|admin\.datatransfer|cloud-identity|apps\.licensing|apps\.order|apps\.groups\.settings|apps\.groups\.migration|ediscovery|script\.projects|script\.deployments)/;
 /** Registering a push channel hands this account's activity to an external URL.
- * It is shaped like a create and behaves like an export, so the verb hides it. */
-const PUSH_REGISTRATION_RE = /(_watch|_subscriptions_create|_subscriptions_reactivate)$/;
+ * It is shaped like a create and behaves like an export, so the verb hides it.
+ * forms.forms.watches.create/renew generate as _watches_create/_watches_renew
+ * (plural "watches", unlike every other API's singular *.watch), so they
+ * need their own branch alongside the common _watch suffix. */
+const PUSH_REGISTRATION_RE = /(_watch|_watches_create|_watches_renew|_subscriptions_create|_subscriptions_reactivate)$/;
 /** Why this write counts as privileged, or undefined if it does not.
  * Derived, not a hand-kept name list: the tool surface is regenerated from
  * Discovery, and a list of names would drift out of date silently. */
@@ -116,6 +119,31 @@ export function isAllowed(tool, policy) {
         return true;
     return profileAllows(policy.profile, tool);
 }
+/**
+ * The escape hatch (google_api_call and every generated per-method tool)
+ * has no allow-list or privileged-write special case of its own anymore:
+ * an explicit deny on any name the operation is known by still wins
+ * (narrows what gets through, never widens it, so listing every curated
+ * tool sharing a raw method here is always safe); full-writes with the
+ * outbound allowlist off is the only automatic allow; everything else
+ * (the default profile, safe-writes, any allow list set, or full-writes
+ * with the allowlist on) asks a human via elicitation instead of
+ * resolving the question itself.
+ */
+export function escapeHatchVerdict(denyNames, base, primaryName, policy, outboundAllowlistActive) {
+    const primaryRef = { name: primaryName, service: base.service, cud: base.cud, scopes: base.scopes };
+    if (base.cud === 'read')
+        return { decision: 'allow', ref: primaryRef };
+    if (policy.readOnly)
+        return { decision: 'deny', ref: primaryRef };
+    const denyRefs = denyNames.map((name) => ({ name, service: base.service, cud: base.cud, scopes: base.scopes }));
+    const deniedRef = denyRefs.find((ref) => matchesAny(ref, policy.deny));
+    if (deniedRef)
+        return { decision: 'deny', ref: deniedRef };
+    if (policy.profile === 'full-writes' && !outboundAllowlistActive)
+        return { decision: 'allow', ref: primaryRef };
+    return { decision: 'ask', ref: primaryRef };
+}
 /** Which profiles would permit this tool at all. */
 function profilesAllowing(tool) {
     return PROFILES.filter((p) => profileAllows(p, tool));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.1",
+  "version": "6.1.0-beta.1",
   "mcpName": "io.github.bakissation/mcp-google-multi",
   "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",

package/skills/google-workspace/SKILL.md

@@ -121,8 +121,8 @@ A write a profile refuses comes back as `{ error: "write_disabled", message,
 hint, retriable: false }` rather than a silent no-op or a generic failure.
 The `hint` names the exact rule that refused it (a deny pattern, the
 privileged-write rule, or the active profile) and what would need to change;
-read it rather than retrying the same call. This applies identically to
-curated tools, generated tools, and the `google_api_call` escape hatch.
+read it rather than retrying the same call. This applies to curated tools.
+A generated tool or `google_api_call` follows a different rule: see section 7.
 
 ## 6. Argument names are exact
 
@@ -153,10 +153,22 @@ If a service has no curated or generated tool for the operation you need
    that method id and whichever of path params, query params, or a JSON body
    it needs.
 
-The escape hatch runs through the same write-control policy as named tools
-(the read/create/update/delete class is derived from the method's HTTP verb
-and name), returns JSON only (binary media is refused with a pointer to
-`drive_download` / `drive_export`), and a response over about 100k
-characters may be cut by the client, so narrow a large request. Prefer a named curated or
-generated tool when one exists: it is more token-lean and better typed than
-building the call by hand.
+A read through the escape hatch is never gated, same as everywhere else. A
+write (the class is derived from the method's HTTP verb and name) follows a
+different rule than named tools: `GOOGLE_READ_ONLY` or a matching
+`GOOGLE_WRITE_DENY` still refuses outright, and `GOOGLE_PROFILE=full-writes`
+(with `GOOGLE_OUTBOUND_ALLOWLIST` unset) still allows outright, but every
+other case, including `GOOGLE_WRITE_ALLOW` (allow lists no longer open the
+escape hatch at all), asks the connected human to confirm the real call
+before it runs. Expect a write through `google_api_call` or a generated
+tool (anything called by its full name directly, not through a curated
+tool) to pause for that confirmation unless the deployment runs
+`full-writes`; a client that cannot be asked gets back `{ error:
+"elicitation_unsupported", ... }` instead, and a decline or cancel comes
+back as `{ error: "write_declined", ... }`; neither is worth retrying
+without changing the write-control configuration or using a curated tool
+instead. The escape hatch returns JSON only (binary media is refused with a
+pointer to `drive_download` / `drive_export`), and a response over about
+100k characters may be cut by the client, so narrow a large request. Prefer
+a named curated or generated tool when one exists: it is more token-lean
+and better typed than building the call by hand.

package/skills/google-workspace/reference/drive.md

@@ -146,7 +146,7 @@ Download a binary file from Drive to local disk. For Google Workspace formats (D
 |---|---|---|---|
 | `account` | string | optional | Google account alias |
 | `fileId` | string | required | Google Drive file ID |
-| `savePath` | string | required | Absolute DIRECTORY path to save into (created if missing, on the machine running the server); the file name comes from `filename` |
+| `savePath` | string | required | Destination folder to save into, on the machine running the server: confined to GOOGLE_LOCAL_FILES_DIR (default <home>/Downloads/mcp-google-multi), created if missing; a relative path resolves inside it, an absolute path must already be inside it. The file name comes from `filename`. |
 | `filename` | string | optional | Filename to save as (defaults to the file name in Drive) |
 
 ## `drive_empty_trash`
@@ -170,7 +170,7 @@ Export a Google Workspace document (Doc, Sheet, Slide) to a standard format and
 | `account` | string | optional | Google account alias |
 | `fileId` | string | required | Google Drive file ID |
 | `mimeType` | string | required | Target export MIME type (e.g. "application/pdf", "text/markdown", "application/vnd.openxmlformats-officedocument.wordprocessingml.document") |
-| `savePath` | string | required | Absolute DIRECTORY path to save into (created if missing, on the machine running the server); the file name comes from `filename` |
+| `savePath` | string | required | Destination folder to save into, on the machine running the server: confined to GOOGLE_LOCAL_FILES_DIR (default <home>/Downloads/mcp-google-multi), created if missing; a relative path resolves inside it, an absolute path must already be inside it. The file name comes from `filename`. |
 | `filename` | string | optional | Filename to save as (defaults to the Drive name plus the extension implied by mimeType) |
 
 ## `drive_get_about`
@@ -464,7 +464,7 @@ Rename, move, or replace content of a Drive file. Any combination in one call. F
 | `fileId` | string | required | Google Drive file ID |
 | `newName` | string | optional | New filename |
 | `newParentFolderId` | string | optional | Move to this folder, named newParentFolderId here, not parentFolderId |
-| `localPath` | string | optional | Replace file content with this local file (path on the machine running the server) |
+| `localPath` | string | optional | Replace file content with this local file, on the machine running the server: confined to GOOGLE_LOCAL_FILES_DIR (default <home>/Downloads/mcp-google-multi); a relative path resolves inside it, an absolute path must already be inside it. |
 | `mimeType` | string | optional | MIME type of the replacement file (required if localPath is provided) |
 | `convertTo` | enum | optional | When replacing content via localPath, convert the new content into this native Google Workspace type on import: "document" \| "spreadsheet" \| "presentation" \| "drawing" (full application/vnd.google-apps.* ids also accepted). |
 
@@ -479,7 +479,7 @@ Upload a file to Google Drive, from inline base64 content or (when this server e
 | `account` | string | optional | Google account alias |
 | `filename` | string | required | Name as it appears in Drive |
 | `contentBase64` | string | optional | Base64-encoded file content. Exactly one of contentBase64 or localPath is required. Decoded size is capped at 10 MB. |
-| `localPath` | string | optional | Absolute path of the SOURCE file on disk to upload (on the machine running the server; this is not savePath). Exactly one of contentBase64 or localPath is required. |
+| `localPath` | string | optional | Path of the SOURCE file to upload, on the machine running the server (this is not savePath): confined to GOOGLE_LOCAL_FILES_DIR (default <home>/Downloads/mcp-google-multi); a relative path resolves inside it, an absolute path must already be inside it. Exactly one of contentBase64 or localPath is required. |
 | `mimeType` | string | optional | Source MIME type of the content (inferred from filename if omitted). With `convertTo`, this is the format Drive imports from. |
 | `convertTo` | enum | optional | Convert the upload into this native Google Workspace type on import: "document" \| "spreadsheet" \| "presentation" \| "drawing" (full application/vnd.google-apps.* ids also accepted). E.g. upload .md/.html/.docx/.txt with convertTo=document to get a real Google Doc. Source must be an importable format. Omit to store the file as-is. |
 | `parentFolderId` | string | optional | Parent folder ID, not parentId. Defaults to My Drive root |

package/skills/google-workspace/reference/gmail.md

@@ -106,7 +106,7 @@ Download an email attachment to local disk. Use gmail_read first to get the atta
 | `messageId` | string | required | The Gmail message ID |
 | `attachmentId` | string | required | The attachment ID from gmail_read response |
 | `filename` | string | required | Filename to save as (e.g. report.xlsx) |
-| `savePath` | string | required | Absolute DIRECTORY path to save into (created if missing, on the machine running the server), e.g. /home/user/Downloads; the file name comes from `filename` |
+| `savePath` | string | required | Destination folder to save into, on the machine running the server: confined to GOOGLE_LOCAL_FILES_DIR (default <home>/Downloads/mcp-google-multi), created if missing; a relative path resolves inside it, an absolute path must already be inside it. The file name comes from `filename`. |
 
 ## `gmail_get_draft`