mcp-google-multi 6.0.0-beta.2 → 6.0.0-beta.4

package/README.md

@@ -44,7 +44,7 @@ New to all this? It's written for someone who just installed Claude Code and has
 5. **Add it to Claude Code, then restart Claude Code:**
 
    ```bash
-   claude mcp add google-multi -s user -- npx -y mcp-google-multi
+   claude mcp add mcp-google-multi -s user -- npx -y mcp-google-multi
    ```
 
 **Stuck at any point? Run `mcp-google-multi doctor`.** It inspects every part and prints the exact fix for anything wrong (a missing sign-in, a Google API you still need to switch on, and so on). Once it reads all-green, just talk to Claude: *"summarize my unread email."*
@@ -55,14 +55,14 @@ New to all this? It's written for someone who just installed Claude Code and has
 
 **Go deeper:** [Configuration reference](./docs/configuration.md) · [What's covered](./COVERAGE.md) · [Features tour](./docs/features.md) · [Remote / HTTP setup](./docs/http-setup.md) · [Secrets in a vault](./docs/secrets.md) · [Local usage metrics](./docs/usage-metrics.md) · [Migrating to v6](./MIGRATION-v6.md) · [Security policy](./SECURITY.md) · [Roadmap](https://github.com/bakissation/mcp-google-multi/milestones)
 
-## Maintainer & credits
+## Maintainer, sponsor & license
 
 Built and maintained by **Abdelbaki Berkati** — [berkati.xyz](https://berkati.xyz) · [@bakissation](https://github.com/bakissation). [Read the case study →](https://berkati.xyz/case-studies/mcp-google-multi/)
 
 Development is **funded by [IdeaCrafters](https://ideacrafters.com)** ([@IdeaCraftersHQ](https://github.com/IdeaCraftersHQ)) — the studio that pays for this OSS to exist.
 
-Thanks to contributors [@obatried](https://github.com/obatried), [@trevor-commits](https://github.com/trevor-commits), and [@mjreddy](https://github.com/mjreddy). The project is maintainer-led (roadmap on [Milestones](https://github.com/bakissation/mcp-google-multi/milestones); bug reports welcome, feature PRs by prior agreement — see [CONTRIBUTING.md](./CONTRIBUTING.md)). **Feedback shapes the roadmap: [open an issue](https://github.com/bakissation/mcp-google-multi/issues/new/choose) with bugs, pain points, or what you wish it did.** Security reports go to [SECURITY.md](./SECURITY.md), never a public issue.
+An Enterprise Edition (hosted, multi-tenant) is available: ask through [berkati.xyz](https://berkati.xyz) (email or LinkedIn there).
 
-## License
+Thanks to contributors [@obatried](https://github.com/obatried), [@trevor-commits](https://github.com/trevor-commits), and [@mjreddy](https://github.com/mjreddy). The project is maintainer-led (roadmap on [Milestones](https://github.com/bakissation/mcp-google-multi/milestones); bug reports welcome, feature PRs by prior agreement — see [CONTRIBUTING.md](./CONTRIBUTING.md)). **Feedback shapes the roadmap: [open an issue](https://github.com/bakissation/mcp-google-multi/issues/new/choose) with bugs, pain points, or what you wish it did.** Security reports go to [SECURITY.md](./SECURITY.md), never a public issue.
 
-[MIT](./LICENSE)
+Licensed under [MIT](./LICENSE).

package/dist/accounts.d.ts

@@ -18,13 +18,17 @@ export interface AccountSet {
     defaultAccount?: string;
     defaultAccountSource?: 'env' | 'config';
 }
-export declare function resolveAccounts(env?: NodeJS.ProcessEnv, filePath?: string, onInvalid?: 'exit' | 'throw'): AccountSet;
+export declare function resolveAccounts(env?: NodeJS.ProcessEnv, filePath?: string, onInvalid?: 'exit' | 'throw', opts?: {
+    tokenDir?: string;
+    emptyOk?: boolean;
+}): AccountSet;
+export declare function fileStamp(filePath: string, version: number): string;
 /** Live accessor: dispatch-time readers use this, never a captured snapshot. */
 export declare function getAccountSet(): AccountSet;
 /** Re-resolve after a config.json mutation and swap the live set. */
 export declare function invalidateAccountSet(): AccountSet;
 export declare function refreshAccountSetIfStale(): void;
-/** Cross-process staleness probe (BR-7): one stat, compared against the stamp. */
+/** Cross-process staleness probe: one stat, compared against the stamp. */
 export declare function isAccountSetStale(): boolean;
 /** Account aliases (possibly empty on a fresh install).
  * Snapshot from the initial load; enums widen only when the registry is
@@ -39,14 +43,26 @@ export declare function unknownAliasMessage(aliases: readonly string[], selector
  * The `account` param schema, empty-registry-safe. A `z.enum` requires at least
  * one value, so a fresh install (zero aliases) would throw at schema-build time
  * (module load) and take down every CLI — including `doctor`, which is meant to
- * REPORT the empty registry (gap #23). Fall back to a plain string when there
+ * REPORT the empty registry. Fall back to a plain string when there
  * are no aliases: no alias exists to enumerate, the server refuses to boot empty
  * anyway, and dispatch validates the account against the live set. */
 export declare function accountAliasSchemaFor(aliases: readonly string[]): z.ZodType<string>;
 /** Shared, load-time snapshot used by every tool's `account` field. */
 export declare const accountAliasSchema: z.ZodType<string>;
+/** Live account argument: validates at PARSE time against the accessor's
+ * CURRENT aliases, so an alias added mid-session (account_add, or a tenant
+ * alias link) is immediately valid on already-registered tools — a baked
+ * z.enum freezes the boot-time set until restart. An empty set stays
+ * permissive (same empty-safe rule as above); dispatch still resolves the
+ * alias against the live registry. */
+export declare function accountArgLive(aliases: () => readonly string[]): z.ZodType<string>;
+/** The live membership check behind accountArgLive and the fan-out field;
+ * `selectors` also admits "*". An empty set stays permissive. */
+export declare function liveAccountCheck(aliases: () => readonly string[], selectors: boolean): z.core.$ZodCheck<string>;
+/** True for a field built on liveAccountCheck, optional or not. */
+export declare function isLiveAccountField(field: unknown): boolean;
 /**
- * BR-4: the stdio/http SERVER never boots with an empty registry — a fresh user
+ * The stdio/http SERVER never boots with an empty registry — a fresh user
  * bootstraps via env / `migrate-config` / `account import` / `auth` first. The
  * bootstrap and diagnostic CLIs return before this guard, so it gates only the
  * server path (called from index.ts after the CLI branches). */

package/dist/accounts.js

@@ -2,8 +2,8 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { z } from 'zod';
 import { loadEnvFiles } from './env-load.js';
-import { CONFIG_VERSION, configDir, configFilePath, failStartup, loadConfigFile, mutateConfigFile } from './config-file.js';
-import { BUNDLE_CATALOG, closestBundle, resolveBundleAliases } from './scope-catalog.js';
+import { ALIAS_RE, CONFIG_VERSION, configDir, configFilePath, failStartup, isReservedAlias, loadConfigFile, mutateConfigFile } from './config-file.js';
+import { closestBundle, isKnownBundle, resolveBundleAliases } from './scope-catalog.js';
 const envLoad = loadEnvFiles();
 const defaultTokenDir = path.join(configDir(), 'tokens');
 const tokenDir = process.env.TOKEN_STORE_PATH
@@ -15,14 +15,14 @@ export function getTokenDir() {
 function parseCsv(value) {
     return (value ?? '').split(',').map((s) => s.trim()).filter(Boolean);
 }
-function accountPaths(alias) {
+function accountPaths(alias, dir = tokenDir) {
     return {
-        tokenPath: path.join(tokenDir, alias, 'token.json'),
-        encPath: path.join(tokenDir, `${alias}.enc`),
+        tokenPath: path.join(dir, alias, 'token.json'),
+        encPath: path.join(dir, `${alias}.enc`),
     };
 }
 /** v5 env parser, guards verbatim. Format: GOOGLE_ACCOUNTS="alias1:email1,alias2:email2". */
-function parseEnvAccounts(raw, adminAliases) {
+function parseEnvAccounts(raw, adminAliases, dir = tokenDir) {
     const configs = {};
     const aliases = [];
     for (const entry of raw.split(',')) {
@@ -40,7 +40,7 @@ function parseEnvAccounts(raw, adminAliases) {
         }
         // Restrict alias to a safe charset so it can't escape `tokenDir` via path traversal
         // (e.g. "../../etc/passwd:foo@bar.com" in .env).
-        if (!/^[a-zA-Z0-9_-]+$/.test(alias) || ['__proto__', 'constructor', 'prototype'].includes(alias)) {
+        if (!ALIAS_RE.test(alias) || isReservedAlias(alias)) {
             throw new Error(`Invalid alias "${alias}". Allowed characters: letters, digits, underscore, hyphen.`);
         }
         if (aliases.includes(alias)) {
@@ -49,7 +49,7 @@ function parseEnvAccounts(raw, adminAliases) {
         aliases.push(alias);
         configs[alias] = {
             email,
-            ...accountPaths(alias),
+            ...accountPaths(alias, dir),
             admin: adminAliases.includes(alias) || undefined,
             source: 'env',
         };
@@ -67,14 +67,17 @@ function noAccountsMessage() {
         `or set GOOGLE_ACCOUNTS=work:user@company.com,personal:user@gmail.com in the environment.${envHint}`);
 }
 /**
- * Registry resolution (BR-2): a non-empty GOOGLE_ACCOUNTS env takes the WHOLE
+ * Registry resolution: a non-empty GOOGLE_ACCOUNTS env takes the WHOLE
  * registry from env (12-factor override, never merged key-by-key); otherwise
  * the registry comes from config.json. GOOGLE_ADMIN_ACCOUNTS, when NON-EMPTY,
  * overrides per-account admin flags from the file (env var > config field);
  * empty behaves as unset, mirroring GOOGLE_ACCOUNTS semantics.
  */
 let warnedLegacy = false;
-export function resolveAccounts(env = process.env, filePath = configFilePath(), onInvalid = 'exit') {
+export function resolveAccounts(env = process.env, filePath = configFilePath(), onInvalid = 'exit', 
+// emptyOk: zero accounts is a valid set, not an error, even with 'throw'.
+opts = {}) {
+    const dir = opts.tokenDir ?? tokenDir;
     const adminEnv = parseCsv(env.GOOGLE_ADMIN_ACCOUNTS);
     const rawEnv = env.GOOGLE_ACCOUNTS;
     const fail = (slug, message) => {
@@ -82,16 +85,15 @@ export function resolveAccounts(env = process.env, filePath = configFilePath(),
             throw new Error(`${slug}: ${message}`);
         failStartup(slug, message);
     };
-    // Validate the legacy global override AT BOOT, whatever GOOGLE_TOOLSETS
-    // selects — otherwise a typo only surfaces at dispatch time inside
-    // account_list instead of the promised startup error (BR3).
+    // Validate at BOOT, or a typo only surfaces at dispatch time inside
+    // account_list instead of the promised startup error.
     const legacyNames = parseCsv(env.GOOGLE_OPTIONAL_SCOPES);
     if (legacyNames.length > 0) {
         for (const bundle of resolveBundleAliases(legacyNames)) {
             if (bundle === 'admin') {
                 fail('E_UNKNOWN_BUNDLE', '"admin" is not a global bundle: grant it per account via GOOGLE_ADMIN_ACCOUNTS or an "admin: true" scope profile.');
             }
-            if (!(bundle in BUNDLE_CATALOG)) {
+            if (!isKnownBundle(bundle)) {
                 const hint = closestBundle(bundle);
                 fail('E_UNKNOWN_BUNDLE', `unknown bundle "${bundle}" in GOOGLE_OPTIONAL_SCOPES${hint ? ` — did you mean "${hint}"?` : ''}`);
             }
@@ -102,7 +104,7 @@ export function resolveAccounts(env = process.env, filePath = configFilePath(),
         }
     }
     if (rawEnv && rawEnv.trim() !== '') {
-        const { aliases, configs } = parseEnvAccounts(rawEnv, adminEnv);
+        const { aliases, configs } = parseEnvAccounts(rawEnv, adminEnv, dir);
         materializeFirstRun(aliases, configs, filePath);
         const def = resolveDefaultAccount(env, null, aliases, fail);
         return {
@@ -116,20 +118,14 @@ export function resolveAccounts(env = process.env, filePath = configFilePath(),
             ...def,
         };
     }
-    // Stat BEFORE read: a cross-process write landing between the two makes the
-    // stamp conservative (flags stale again next dispatch) instead of pinning
-    // stale content behind a fresh stamp.
+    // Stat BEFORE read, so a race lands on the conservative (stale) side.
     const preStamp = fileStamp(filePath, CONFIG_VERSION);
     const config = loadConfigFile(filePath, onInvalid);
     const entries = Object.entries(config?.accounts ?? {});
     if (entries.length === 0) {
-        // Gap #23: an empty registry is NOT fatal at resolve time — the bootstrap and
-        // diagnostic CLIs (doctor/reset/account import/migrate-config/config check)
-        // must run on a fresh install. Only the stdio/http SERVER refuses to boot
-        // empty (BR-4), enforced by assertServerAccountsConfigured() in index.ts.
-        // The dispatch-path reload ('throw') still throws so a mid-session emptied
-        // config.json keeps the last-good registry (BR-7) instead of dropping tools.
-        if (onInvalid === 'throw') {
+        // Not fatal here: bootstrap/diagnostic CLIs must run on a fresh install;
+        // only the server refuses to boot empty (index.ts).
+        if (onInvalid === 'throw' && !opts.emptyOk) {
             throw new Error(`E_NO_ACCOUNTS_CONFIGURED: ${noAccountsMessage()}`);
         }
         return {
@@ -140,15 +136,14 @@ export function resolveAccounts(env = process.env, filePath = configFilePath(),
             stamp: `${config?.version ?? CONFIG_VERSION}:${preStamp.split(':')[1]}`,
         };
     }
-    // BR3: unknown bundle names fail loudly (a mis-scoped token is worse than a
-    // clear error); v5 silently filtered them. Null prototype: profile names are
-    // user input and must never collide with Object.prototype members.
+    // Unknown bundle names fail loudly (a mis-scoped token is worse than a clear
+    // error). Null prototype: profile names are user input, must never collide with Object.prototype.
     const scopeProfiles = Object.create(null);
     scopeProfiles.base = { bundles: [] };
     for (const [name, profile] of Object.entries(config?.scopeProfiles ?? {})) {
         const bundles = resolveBundleAliases(profile.bundles);
         for (const bundle of bundles) {
-            if (!(bundle in BUNDLE_CATALOG)) {
+            if (!isKnownBundle(bundle)) {
                 const hint = closestBundle(bundle);
                 fail('E_UNKNOWN_BUNDLE', `unknown bundle "${bundle}" in scope profile "${name}"${hint ? ` — did you mean "${hint}"?` : ''}`);
             }
@@ -167,7 +162,7 @@ export function resolveAccounts(env = process.env, filePath = configFilePath(),
         aliases.push(alias);
         configs[alias] = {
             email: entry.email,
-            ...accountPaths(alias),
+            ...accountPaths(alias, dir),
             scopeProfile: entry.scopeProfile,
             admin: adminEnv.length > 0 ? adminEnv.includes(alias) : entry.admin,
             source: 'config',
@@ -183,9 +178,8 @@ export function resolveAccounts(env = process.env, filePath = configFilePath(),
         ...def,
     };
 }
-/** A2: env GOOGLE_DEFAULT_ACCOUNT > config.defaultAccount > unset. A configured
- * default naming an unknown alias refuses to start (E_DEFAULT_ACCOUNT_UNKNOWN —
- * deliberately NOT E_CONFIG_INVALID: the config is schema-valid). */
+// env GOOGLE_DEFAULT_ACCOUNT > config.defaultAccount > unset; an unknown alias
+// refuses to start as E_DEFAULT_ACCOUNT_UNKNOWN, not E_CONFIG_INVALID (the config is schema-valid).
 function resolveDefaultAccount(env, fromConfig, aliases, fail) {
     const fromEnv = env.GOOGLE_DEFAULT_ACCOUNT?.trim();
     const value = fromEnv || fromConfig || undefined;
@@ -196,7 +190,7 @@ function resolveDefaultAccount(env, fromConfig, aliases, fail) {
     }
     return { defaultAccount: value, defaultAccountSource: fromEnv ? 'env' : 'config' };
 }
-function fileStamp(filePath, version) {
+export function fileStamp(filePath, version) {
     try {
         return `${version}:${fs.statSync(filePath).mtimeMs}`;
     }
@@ -204,17 +198,14 @@ function fileStamp(filePath, version) {
         return `${version}:0`;
     }
 }
-// First-run shim (BC6): env is set and no config.json exists yet — materialize
-// the file so the wizard has something to edit. Env still wins this session;
-// a write failure must never block boot (warn on stderr and continue).
+// env is set and no config.json exists yet: materialize the file so the
+// wizard has something to edit; a write failure must never block boot.
 function materializeFirstRun(aliases, configs, filePath) {
     if (fs.existsSync(filePath))
         return;
     try {
         let wrote = false;
-        // mutateConfigFile = lock + re-check + atomic write, so a concurrent
-        // wizard/migrate writer is never clobbered (the loaded `current` is
-        // re-read under the lock; only a still-absent file gets the env content).
+        // lock + re-check + atomic write, so a concurrent wizard/migrate writer is never clobbered.
         mutateConfigFile((current) => {
             if (Object.keys(current.accounts ?? {}).length > 0)
                 return current;
@@ -247,7 +238,7 @@ export function invalidateAccountSet() {
     return current;
 }
 /**
- * Dispatch-path reload (BR-7): NEVER exits and never throws — a mid-edit,
+ * Dispatch-path reload: NEVER exits and never throws — a mid-edit,
  * corrupt, or deleted config.json keeps the last-good set and warns once per
  * distinct failure on stderr. failStartup semantics are boot/CLI-only.
  */
@@ -267,7 +258,7 @@ export function refreshAccountSetIfStale() {
         }
     }
 }
-/** Cross-process staleness probe (BR-7): one stat, compared against the stamp. */
+/** Cross-process staleness probe: one stat, compared against the stamp. */
 export function isAccountSetStale() {
     if (current.source !== 'file')
         return false;
@@ -283,6 +274,8 @@ export const ACCOUNTS = current.aliases;
  * enum actually accepts, and naming a runtime-added alias as valid while
  * rejecting it would be a lie. */
 export function unknownAliasMessage(aliases, selectors = false) {
+    if (aliases.length === 0)
+        return 'No Google account is configured yet. Add one with account_add.';
     const all = selectors ? '; "*" for all accounts' : '';
     const csv = selectors && aliases.length > 1 ? `; or a CSV subset like "${aliases.slice(0, 2).join(',')}"` : '';
     return `Unknown account alias. Valid: ${aliases.join(', ')}${all}${csv}. Run account_list if accounts changed since this server started.`;
@@ -291,7 +284,7 @@ export function unknownAliasMessage(aliases, selectors = false) {
  * The `account` param schema, empty-registry-safe. A `z.enum` requires at least
  * one value, so a fresh install (zero aliases) would throw at schema-build time
  * (module load) and take down every CLI — including `doctor`, which is meant to
- * REPORT the empty registry (gap #23). Fall back to a plain string when there
+ * REPORT the empty registry. Fall back to a plain string when there
  * are no aliases: no alias exists to enumerate, the server refuses to boot empty
  * anyway, and dispatch validates the account against the live set. */
 export function accountAliasSchemaFor(aliases) {
@@ -301,8 +294,39 @@ export function accountAliasSchemaFor(aliases) {
 }
 /** Shared, load-time snapshot used by every tool's `account` field. */
 export const accountAliasSchema = accountAliasSchemaFor(ACCOUNTS);
+/** Live account argument: validates at PARSE time against the accessor's
+ * CURRENT aliases, so an alias added mid-session (account_add, or a tenant
+ * alias link) is immediately valid on already-registered tools — a baked
+ * z.enum freezes the boot-time set until restart. An empty set stays
+ * permissive (same empty-safe rule as above); dispatch still resolves the
+ * alias against the live registry. */
+export function accountArgLive(aliases) {
+    return z.string().check(liveAccountCheck(aliases, false));
+}
+// The check instance survives the clones .describe() and .optional() make,
+// so it is what marks a field as an account selector for the registry.
+const LIVE_ACCOUNT_CHECKS = new WeakSet();
+/** The live membership check behind accountArgLive and the fan-out field;
+ * `selectors` also admits "*". An empty set stays permissive. */
+export function liveAccountCheck(aliases, selectors) {
+    const check = z.superRefine((value, ctx) => {
+        const current = aliases();
+        if (current.length === 0 || current.includes(value) || (selectors && value === '*'))
+            return;
+        ctx.addIssue({ code: 'custom', message: unknownAliasMessage(current, selectors) });
+    });
+    LIVE_ACCOUNT_CHECKS.add(check);
+    return check;
+}
+/** True for a field built on liveAccountCheck, optional or not. */
+export function isLiveAccountField(field) {
+    let def = field?._zod?.def;
+    if (def?.type === 'optional')
+        def = def.innerType?._zod?.def;
+    return def?.checks?.some((c) => LIVE_ACCOUNT_CHECKS.has(c)) ?? false;
+}
 /**
- * BR-4: the stdio/http SERVER never boots with an empty registry — a fresh user
+ * The stdio/http SERVER never boots with an empty registry — a fresh user
  * bootstraps via env / `migrate-config` / `account import` / `auth` first. The
  * bootstrap and diagnostic CLIs return before this guard, so it gates only the
  * server path (called from index.ts after the CLI branches). */

package/dist/api-probe.d.ts

@@ -1,3 +1,5 @@
+import { getClient } from './client.js';
+import { readToken } from './token-store.js';
 import type { ApiProbeResult } from './doctor.js';
 export interface ApiProbeSpec {
     service: string;
@@ -15,4 +17,7 @@ export interface ApiProbeDeps {
     grantedScopes: (alias: string) => string[];
     request: (alias: string, url: string) => Promise<void>;
 }
+/** Probe deps over one context's token reads and client; the module-level
+ * pair is the single owner's. */
+export declare function apiProbeDepsFor(readTokenFn: typeof readToken, getClientFn: typeof getClient): ApiProbeDeps;
 export declare function probeApiEnablement(alias: string, deps?: ApiProbeDeps): Promise<ApiProbeResult[]>;

package/dist/api-probe.js

@@ -24,21 +24,26 @@ export const API_PROBES = [
 export function planProbes(granted, probes = API_PROBES) {
     return probes.filter((p) => granted.some((s) => p.scopePrefixes.some((prefix) => s.startsWith(prefix))));
 }
-const DEFAULT_DEPS = {
-    grantedScopes: (alias) => {
-        try {
-            const scope = readToken(alias)?.scope;
-            return typeof scope === 'string' ? scope.split(' ').filter(Boolean) : [];
-        }
-        catch {
-            return [];
-        }
-    },
-    request: async (alias, url) => {
-        const auth = await getClient(alias);
-        await auth.request({ url, timeout: 10_000 });
-    },
-};
+/** Probe deps over one context's token reads and client; the module-level
+ * pair is the single owner's. */
+export function apiProbeDepsFor(readTokenFn, getClientFn) {
+    return {
+        grantedScopes: (alias) => {
+            try {
+                const scope = readTokenFn(alias)?.scope;
+                return typeof scope === 'string' ? scope.split(' ').filter(Boolean) : [];
+            }
+            catch {
+                return [];
+            }
+        },
+        request: async (alias, url) => {
+            const auth = await getClientFn(alias);
+            await auth.request({ url, timeout: 10_000 });
+        },
+    };
+}
+const DEFAULT_DEPS = apiProbeDepsFor(readToken, getClient);
 export async function probeApiEnablement(alias, deps = DEFAULT_DEPS) {
     const results = [];
     for (const spec of planProbes(deps.grantedScopes(alias))) {

package/dist/arg-normalize.js

@@ -1,10 +1,7 @@
-import { screenArguments, unknownArgEnvelope, } from './arg-strict.js';
-import { sliceClean } from './trim.js';
-// The SDK synthesizes input-validation failures as isError RESULTS, skipping
-// the handler entirely: no handler of ours runs, so no envelope exists and the
-// client gets free text. The text is prose in both SDK eras (v1 prefixed it
-// with "MCP error -32602: ", v2 dropped that prefix), while handler envelopes
-// are always JSON starting with "{".
+import { echoName, echoNames, screenArguments, unknownArgEnvelope, } from './arg-strict.js';
+import { logSafe, sliceClean } from './trim.js';
+// The SDK synthesizes input-validation failures as isError RESULTS (no handler
+// runs), so the client gets free prose; handler envelopes always start with "{".
 const SCHEMA_VALIDATION_TEXT = /^(MCP error -32602: )?Input validation error:/;
 export function isSchemaValidationText(text) {
     return SCHEMA_VALIDATION_TEXT.test(text);
@@ -12,18 +9,11 @@ export function isSchemaValidationText(text) {
 /** Capture form of the v2 text. The tool-name class excludes ':' and ' ', so
  * the first ": " after the name is unambiguously the delimiter. */
 const VALIDATION_PROSE = /^(?:MCP error -32602: )?Input validation error: Invalid arguments for tool ([A-Za-z0-9_.-]+): ([\s\S]+)$/;
-/** The SDK's OTHER synthesized prose on the same catch. Both prefixes are
- * SDK-authored; a HANDLER's free text is not, and must survive untouched
- * (the account wizard answers in prose today). */
+/** The SDK's OTHER synthesized prose on the same catch; a HANDLER's free text
+ * is not SDK-authored and must survive untouched. */
 const SDK_OUTPUT_PROSE = /^(?:MCP error -32602: )?Output validation error: /;
-// Wire-level tools/call argument normalization. Clients (LLMs) recurringly
-// snake_case a camelCase parameter (thread_id for threadId) and burn a retry
-// on the -32602. A schema-level fix is off the table: the SDK advertises an
-// EMPTY input schema for any non-object wrapper (pipe/preprocess), so the
-// only seam that keeps tools/list intact is the JSON-RPC message itself —
-// which is versioned MCP spec, stabler than any SDK internal. The rename is
-// provably lossless: it fires only when the sent key is NOT in the tool's
-// schema, its camelCase twin IS, and that twin was not also sent.
+// Wire-level, not schema-level: the SDK advertises an EMPTY input schema for
+// any non-object wrapper, so the JSON-RPC message is the only stable seam. See docs/internals.md.
 export function argNormalizationEnabled(env = process.env) {
     return !/^(0|false|off|no)$/i.test((env.GOOGLE_ARG_NORMALIZE ?? '').trim());
 }
@@ -94,11 +84,8 @@ export function screenMessage(msg, opts, log = (l) => process.stderr.write(`${l}
         return { action: 'forward', msg };
     const tool = m.params.name;
     const declared = opts.declaredFor(tool);
-    // Unregistered tool. The spec keeps this a PROTOCOL error (unknown tool is
-    // not something the model can fix by adjusting arguments), so the channel
-    // stays a JSON-RPC error; only the message gets the did-you-mean and the
-    // gated-service next step. Without `unknownTool`, or on a notification,
-    // the SDK's own "not found" still answers.
+    // Unregistered tool stays a PROTOCOL error (not an arguments problem); only
+    // the message gets the did-you-mean. No `unknownTool`, or a notification: the SDK's own answers.
     if (!declared) {
         if (!opts.unknownTool || m.id === undefined)
             return { action: 'forward', msg };
@@ -115,8 +102,8 @@ export function screenMessage(msg, opts, log = (l) => process.stderr.write(`${l}
     if (screened.unknown.length === 0 && screened.redundant.length === 0)
         return { action: 'forward', msg };
     const all = [...screened.unknown.map((u) => u.sent), ...screened.redundant];
-    // Key names only; argument VALUES never reach the log.
-    log(`[args] ${tool}: undeclared ${all.join(', ')}${opts.mode === 'warn' ? ' (dropped)' : ' (rejected)'}`);
+    // Key names only, escaped here and only here: the caller's names, never values, reach the log.
+    log(`[args] ${tool}: undeclared ${logSafe(echoNames(all), 600)}${opts.mode === 'warn' ? ' (dropped)' : ' (rejected)'}`);
     try {
         // Only ever a DECLARED key or the literal placeholder, so the metrics
         // closed-vocabulary rule holds: the caller's key is never persisted.
@@ -132,7 +119,7 @@ export function screenMessage(msg, opts, log = (l) => process.stderr.write(`${l}
     const siblings = screened.unknown.some((u) => u.suggestions.length > 0)
         ? []
         : (opts.siblingsFor?.(tool, screened.unknown.map((u) => u.sent)) ?? []);
-    const envelope = unknownArgEnvelope(tool, screened.unknown, declared, typeof account === 'string' ? account : undefined, siblings);
+    const envelope = unknownArgEnvelope(tool, screened.unknown, declared, typeof account === 'string' ? echoName(account) : undefined, siblings);
     return {
         action: 'reject',
         response: {
@@ -166,13 +153,10 @@ export function withArgNormalization(transport, shapeFor, log, onRename, strict)
                     if (outcome.action === 'forward')
                         return handler(outcome.msg, extra);
                     // Last-resort fallback: dispatch as before rather than hang the
-                    // caller. The stderr line and the counter already fired above.
-                    // `send` is async, so a rejected promise needs catching too: a
-                    // bare `void` left the client waiting for a frame that never came.
+                    // caller; send is async, so a bare `void` would leave it waiting forever on rejection.
                     const fallback = () => handler(normalized, extra);
                     try {
-                        // Answer on the INNER transport so the metrics tap still sees the
-                        // frame and clears its pending id.
+                        // On the INNER transport so the metrics tap still sees the frame and clears its pending id.
                         void Promise.resolve(transport.send(outcome.response)).catch(fallback);
                     }
                     catch {
@@ -194,10 +178,8 @@ export function withArgNormalization(transport, shapeFor, log, onRename, strict)
     if (transport.setProtocolVersion) {
         wrapper.setProtocolVersion = (v) => transport.setProtocolVersion(v);
     }
-    // v2-only, called by Protocol.connect() before start(). A no-op today (both
-    // sides default to the same exported constant), but a proxy that silently
-    // eats a member the SDK calls is a bug waiting for the first caller that
-    // passes supportedProtocolVersions explicitly.
+    // A no-op today, but a proxy silently eating an SDK-called member is a bug
+    // waiting for the first caller that passes this explicitly.
     if (transport.setSupportedProtocolVersions) {
         wrapper.setSupportedProtocolVersions = (v) => transport.setSupportedProtocolVersions(v);
     }
@@ -229,9 +211,8 @@ export function outputFailureEnvelope(tool, text, account) {
 }
 export function rewriteValidationFrame(message, pending, opts) {
     const m = message;
-    // Responses only. A server-initiated REQUEST (elicitation, sampling) also
-    // carries an id, from a different id space, and evicting on it would drop a
-    // real pending call.
+    // Responses only: a server-initiated REQUEST also carries an id (a
+    // different id space), and evicting on it would drop a real pending call.
     if (m.id === undefined || m.method !== undefined)
         return message;
     const call = pending.get(m.id);

package/dist/arg-strict.d.ts

@@ -14,6 +14,13 @@ export declare const STRICT_EXEMPT_TOOLS: ReadonlySet<string>;
  * tools: no declared key starts with `_` or contains `/`, so neither rule can
  * shadow a real parameter. */
 export declare function isExemptKey(key: string): boolean;
+/** A call can carry thousands of unknown keys, or one of megabytes: only the
+ * first few earn a did-you-mean, and the log line and the envelope echo a
+ * bounded prefix of each name. The reject decision itself is never capped. */
+export declare const MAX_SUGGESTED_KEYS = 8;
+export declare function echoName(name: string): string;
+/** The first MAX_SUGGESTED_KEYS names, each capped, then "and N more". */
+export declare function echoNames(names: readonly string[], quote?: boolean): string;
 /**
  * Rank declared keys for an unknown key. Tiers, best non-empty tier wins:
  *   0 same key modulo case and separators