gogcli-mcp 4.2.5 → 4.4.0

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "4.2.5",
+  "version": "4.4.0",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",
@@ -37,7 +37,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}"
       }
     }
   },
@@ -53,6 +54,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",
-  "version": "4.2.5",
+  "version": "4.4.0",
   "mcpName": "io.github.chrischall/gogcli-mcp",
   "description": "MCP server wrapping gogcli for Google service access",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -41,7 +41,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/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp"
   },
-  "version": "4.2.5",
+  "version": "4.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp",
-      "version": "4.2.5",
+      "version": "4.4.0",
       "transport": {
         "type": "stdio"
       },

package/src/arg-guard.ts

@@ -0,0 +1,68 @@
+// Guards for argv this wrapper does NOT build itself.
+//
+// The `gog_<service>_run` escape hatches forward a model-supplied string[]
+// verbatim. gog (kong) takes the LAST value of a repeated flag, so an arg like
+// `--readonly=false` placed after the runner's injected `--readonly` silently
+// re-enables writes on a deployment the operator locked read-only — the one
+// kill switch an operator can set (audit SEC-1). The same holds for every
+// other global that is a control rather than an option: the command allow/deny
+// lists, the credential source (`--access-token`, `--home`, `--client`), the
+// account, `--gmail-no-send` and `--no-input`.
+//
+// A bare `--` is refused as well. It ends flag parsing, so anything the wrapper
+// appends AFTER it (a safety flag appended last, for instance) would be read as
+// a positional and quietly dropped.
+//
+// Kept out of runner.ts on purpose: tool tests automock the runner module, and
+// these checks have to run for real inside the tool handlers.
+
+// Long-flag names whose override the model must never control, matched as
+// EXACT names: the flag alone (`--readonly`) or with an attached value
+// (`--readonly=false`), case-insensitively. Not as bare prefixes — that refused
+// legitimate command flags that merely share a leading word, such as
+// gog_zoom_auth_setup's --account-id / --client-id / --client-secret. gog has
+// no flag abbreviation, so a longer spelling is a different flag, not an
+// override.
+const 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;
+
+// `-a` is the short form of --account. kong accepts short-flag CLUSTERS
+// (`-ja` = `-j -a`) and an attached value (`-aother@x`), so any single-dash
+// token whose letters include `a` is refused. `-5` (a negative number) and
+// `-y` (force) are unaffected.
+const SHORT_ACCOUNT_CLUSTER = /^-(?!-)[A-Za-z]*a/;
+
+/** Why `arg` may not be forwarded to gog, or undefined when it is fine. */
+export function forbiddenArgReason(arg: string): string | undefined {
+  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 undefined;
+}
+
+/** Throw on the first model-supplied arg that would override a gog safety control. */
+export function assertSafeForwardedArgs(args: readonly string[]): void {
+  for (const arg of args) {
+    const reason = forbiddenArgReason(arg);
+    if (reason) throw new Error(reason);
+  }
+}
+
+// A gog subcommand is a lower-case word, possibly hyphenated (`mark-read`).
+// Anything else — a flag, an empty string, a path — is a smuggling attempt or a
+// mistake, and gog would parse it as something other than a subcommand.
+const SUBCOMMAND_SHAPE = /^[a-z][a-z0-9-]*$/;
+
+export function assertSafeSubcommand(subcommand: string): void {
+  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.`,
+    );
+  }
+}

package/src/argv.ts

@@ -0,0 +1,27 @@
+// Positional-argument marking for gog argv (audit BUG-1).
+//
+// A tool's positional values — a Gmail query, a file ID, a range, a name — are
+// chosen by the model. Pushed as bare argv elements, one that starts with '-'
+// is parsed by gog (kong) as a flag: `gog gmail search "-in:spam"` fails with
+// "unknown flag -i", and a value starting with `--` becomes a real gog flag.
+// Wrapping each value in pos() tells the runner to place it after a single
+// `--`, after every flag, which is how upstream gogcli's own MCP tools call it
+// (internal/cmd/mcp_tools.go).
+//
+// Lives outside runner.ts on purpose: tool tests automock the runner module,
+// and pos() must stay a real function there.
+
+export interface GogPositional {
+  /** Discriminant separating this from a plain argv string and a GogFileArg. */
+  kind: 'positional';
+  value: string;
+}
+
+/** Mark a model-supplied positional value so it is passed after `--`. */
+export function pos(value: string): GogPositional {
+  return { kind: 'positional', value };
+}
+
+export function isGogPositional(arg: unknown): arg is GogPositional {
+  return typeof arg === 'object' && arg !== null && (arg as { kind?: unknown }).kind === 'positional';
+}

package/src/attachment-root.ts

@@ -0,0 +1,111 @@
+// The private, self-cleaning directory attachment downloads land in (audit SEC-6).
+//
+// It used to be a fixed `/tmp/gog-attachments` that nothing ever emptied, so
+// every downloaded attachment — medical records, statements, custody documents
+// — piled up in world-traversable /tmp for the life of the host. And because
+// the name was predictable and shared, another local user could pre-create it
+// or plant a symlink there, redefining where the blob-upload "confinement"
+// root pointed.
+//
+// Now the root is per-user (named for the uid, under the OS temp dir), created
+// owner-only (0700), and verified before every use: a symlink, a non-directory
+// or a directory owned by someone else is refused rather than trusted. Files a
+// caller never sees again (inline, Drive and URL deliveries) are deleted as
+// soon as they are delivered; files returned BY PATH are kept for the caller to
+// read and swept once they are older than ATTACHMENT_TTL_MS.
+
+import { tmpdir, userInfo } from 'node:os';
+import { dirname, join, relative, resolve, isAbsolute, sep } from 'node:path';
+
+/** Where gmail attachment downloads are written, and the only tree the blob upload reads from. */
+export const ATTACHMENT_DOWNLOAD_ROOT = join(tmpdir(), `gogcli-mcp-attachments-${userInfo().uid}`);
+
+/** How long a download returned by path is kept before a later download sweeps it. */
+export const ATTACHMENT_TTL_MS = 24 * 60 * 60 * 1000;
+
+function isInside(root: string, target: string): boolean {
+  const rel = relative(root, target);
+  return rel !== '' && !rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel);
+}
+
+/**
+ * Create `dir` owner-only if missing, then verify it: a real directory (not a
+ * symlink), owned by this user, with no group/other permissions (tightened to
+ * 0700 when it is ours but looser). `opts.uid` is injected by tests.
+ */
+export async function ensurePrivateDir(dir: string, opts: { uid?: number } = {}): Promise<void> {
+  const { mkdir, lstat, chmod } = await import('node:fs/promises');
+  try {
+    await mkdir(dir, { mode: 0o700 });
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+  }
+  const info = await lstat(dir);
+  if (info.isSymbolicLink() || !info.isDirectory()) {
+    throw new Error(`refusing to use ${dir} for attachment downloads: it is not a real directory`);
+  }
+  const uid = opts.uid ?? userInfo().uid;
+  if (info.uid !== uid) {
+    throw new Error(`refusing to use ${dir} for attachment downloads: it is owned by another user`);
+  }
+  if ((info.mode & 0o077) !== 0) await chmod(dir, 0o700);
+}
+
+/**
+ * Delete top-level entries of `root` last modified more than `ttlMs` ago.
+ * Best-effort: a missing root sweeps nothing, and one entry failing never stops
+ * the rest. Returns how many entries were removed.
+ */
+export async function sweepExpiredDownloads(
+  root: string = ATTACHMENT_DOWNLOAD_ROOT,
+  ttlMs: number = ATTACHMENT_TTL_MS,
+  now: number = Date.now(),
+): Promise<number> {
+  const { readdir, lstat, rm } = await import('node:fs/promises');
+  let entries: string[];
+  try {
+    entries = await readdir(root);
+  } catch {
+    return 0;
+  }
+  let removed = 0;
+  for (const name of entries) {
+    const path = join(root, name);
+    try {
+      const info = await lstat(path);
+      if (now - info.mtimeMs > ttlMs) {
+        await rm(path, { recursive: true, force: true });
+        removed += 1;
+      }
+    } catch {
+      // raced with another sweep or a delivery cleanup — nothing to do
+    }
+  }
+  return removed;
+}
+
+/**
+ * Delete one delivered download, then any directories it leaves empty, up to
+ * (never including) `root`. A path outside `root` is left alone: this only
+ * ever cleans up after the server's own downloads, never a caller's `out`.
+ */
+export async function removeDownload(path: string, root: string = ATTACHMENT_DOWNLOAD_ROOT): Promise<void> {
+  const { rm, rmdir } = await import('node:fs/promises');
+  const base = resolve(root);
+  const target = resolve(base, path);
+  if (!isInside(base, target)) return;
+  await rm(target, { force: true });
+  for (let dir = dirname(target); isInside(base, dir); dir = dirname(dir)) {
+    try {
+      await rmdir(dir);
+    } catch {
+      break; // not empty (or already gone): stop climbing
+    }
+  }
+}
+
+/** Make the download root private and sweep expired downloads out of it. */
+export async function prepareDownloadRoot(root: string = ATTACHMENT_DOWNLOAD_ROOT): Promise<void> {
+  await ensurePrivateDir(root);
+  await sweepExpiredDownloads(root);
+}

package/src/attachments.ts

@@ -80,6 +80,7 @@ export const MAX_INLINE_ATTACHMENT_TOTAL_BYTES = Math.floor((MAX_REQUEST_PAYLOAD
  */
 function wireBytesOf(arg: GogArg): number {
   if (typeof arg === 'string') return Buffer.byteLength(arg, 'utf8');
+  if (arg.kind === 'positional') return Buffer.byteLength(arg.value, 'utf8');
   return arg.encoding === 'base64' ? arg.contents.length : Buffer.byteLength(arg.contents, 'utf8');
 }
 

package/src/blob-upload.ts

@@ -25,9 +25,11 @@
 /**
  * Where gmail's attachment download writes (`defaultOutPath` in
  * packages/gogcli-mcp-gmail/src/tools/gmail-extra.ts) and the only tree this
- * module will read back from.
+ * module will read back from. Per-user and private — see attachment-root.ts.
  */
-export const ATTACHMENT_DOWNLOAD_ROOT = '/tmp/gog-attachments';
+import { ATTACHMENT_DOWNLOAD_ROOT } from './attachment-root.js';
+
+export { ATTACHMENT_DOWNLOAD_ROOT };
 
 /** mcp-host's blob store caps one object at 100 MiB and answers 413 past it. */
 export const MAX_BLOB_UPLOAD_BYTES = 100 * 1024 * 1024;

package/src/dispatch-confirmation.ts

@@ -0,0 +1,277 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import type { CallToolResult, InputRequiredResult, ServerContext } from '@modelcontextprotocol/server';
+import { callerAcceptsFormElicitation, readEnvVar, requireConfirmation, textResult } from '@chrischall/mcp-utils';
+import { z } from 'zod';
+import {
+  confirmTokenTtlSeconds,
+  hashSendPayload,
+  issueConfirmToken,
+  sendConfirmFallbackEnabled,
+  verifyConfirmToken,
+  type ConfirmBinding,
+  type ConfirmTokenError,
+} from './send-confirm-token.js';
+
+// ============================================================================
+// THE DISPATCH RAIL, service-neutral: every tool that reaches another person
+// (Gmail sends, Chat posts, guest-visible Calendar changes, Drive shares,
+// Classroom announcements and invitations) asks the user first.
+//
+// Elicitation is primary: the host shows the preview and the model never holds
+// the approval. On a client that declares no elicitation (claude.ai, measured),
+// the call is refused — unless the call site supplies a `DispatchTokenFallback`
+// and the server opted in with GOG_SEND_CONFIRM_FALLBACK=token, in which case
+// the two-phase preview + confirmToken flow (send-confirm-token.ts) runs instead.
+// ============================================================================
+
+// Bound on the body text shown in a confirmation prompt. Enough to read what is
+// actually being sent (the point of SEC-5), small enough to keep the prompt a
+// prompt rather than a copy of the message.
+export const BODY_PREVIEW_MAX = 2048;
+
+/** The first BODY_PREVIEW_MAX characters of a body, marked when cut. */
+export function bodyPreview(text: string | undefined): string | undefined {
+  if (!text) return undefined;
+  if (text.length <= BODY_PREVIEW_MAX) return text;
+  return `${text.slice(0, BODY_PREVIEW_MAX)}… [${text.length - BODY_PREVIEW_MAX} more characters not shown]`;
+}
+
+/**
+ * Every attachment a dispatch will carry: a server path in full (so the user
+ * sees WHICH file on the gog host is leaving), an inline one by its filename.
+ */
+export function attachmentNames(
+  paths: readonly string[] | undefined,
+  inline: ReadonlyArray<{ filename: string }> | undefined,
+): string[] {
+  return [...(paths ?? []), ...(inline ?? []).map((a) => a.filename)];
+}
+
+/** One attachment as the fallback preview shows it and its hash binds it. */
+export type AttachmentDetail = { name: string; size: number | null; sha256?: string };
+
+/**
+ * Name, byte size and content SHA-256 of every file a dispatch carries, for the
+ * token fallback's preview and payload hash. A server path is read (it is
+ * already confined to GOG_FILE_ROOTS) so a same-size swap between the phases is
+ * still a changed payload; an unreadable one reports `size: null` and gog will
+ * fail on it anyway.
+ */
+export function attachmentDetails(
+  paths: readonly string[] | undefined,
+  inline: ReadonlyArray<{ filename: string; contentBase64: string }> | undefined,
+): AttachmentDetail[] {
+  const out: AttachmentDetail[] = [];
+  for (const path of paths ?? []) {
+    let bytes: Buffer | undefined;
+    try {
+      bytes = readFileSync(path);
+    } catch {
+      bytes = undefined;
+    }
+    out.push(bytes
+      ? { name: path, size: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') }
+      : { name: path, size: null });
+  }
+  for (const a of inline ?? []) {
+    out.push({
+      name: a.filename,
+      size: Buffer.from(a.contentBase64, 'base64').length,
+      sha256: createHash('sha256').update(a.contentBase64).digest('hex'),
+    });
+  }
+  return out;
+}
+
+/** Who a dispatch goes out as, for the fallback preview: an explicit alias, else the account. */
+export function senderPreview(account: string | undefined, from?: string): string {
+  return from ?? account ?? readEnvVar('GOG_ACCOUNT') ?? "the gog account's default address";
+}
+
+/** Drop the fingerprint for display: the user needs a name and a size. */
+export function attachmentPreview(details: readonly AttachmentDetail[]): Array<{ name: string; size: number | null }> {
+  return details.map(({ name, size }) => ({ name, size }));
+}
+
+/** The instruction a mail dispatch's phase 1 carries — verbatim from the spec that introduced the fallback. */
+export const CONFIRM_SEND_INSTRUCTION =
+  'Show this preview to the user verbatim and send only after they explicitly approve in chat. '
+  + 'Then call again with confirmToken.';
+
+/** The same instruction for a dispatch that is not mail (a share, an invitation, a post). */
+export const CONFIRM_ACTION_INSTRUCTION =
+  'Show this preview to the user verbatim and proceed only after they explicitly approve in chat. '
+  + 'Then call again with confirmToken.';
+
+const FALLBACK_HINT = 'Or set GOG_SEND_CONFIRM_FALLBACK=token to enable two-step confirmation.';
+
+/** Appended to each gated tool's description. */
+export const CONFIRM_FALLBACK_DESCRIPTION =
+  ' If the client cannot show that prompt (no MCP elicitation, e.g. claude.ai) and the server sets '
+  + 'GOG_SEND_CONFIRM_FALLBACK=token, a two-step flow applies instead: call WITHOUT confirmToken and nothing is '
+  + 'sent or changed — the result has status "confirmation-required", the full preview and a confirmToken. Show that preview '
+  + 'to the user verbatim; only after they explicitly approve it in chat, call again with the SAME arguments plus '
+  + 'confirmToken. The tool re-reads what it would act on and refuses (DRAFT_CHANGED, with a fresh preview and token) '
+  + 'if it changed; TOKEN_EXPIRED / TOKEN_REUSED / TOKEN_INVALID also do nothing.';
+
+export const confirmTokenParam = z.string().optional().describe(
+  'ONLY for the two-step fallback (client without MCP elicitation, server with GOG_SEND_CONFIRM_FALLBACK=token). '
+  + 'The confirmToken from this same tool\'s phase-1 "confirmation-required" response, passed back ONLY after the user '
+  + 'has seen that preview and explicitly approved it in chat — never on the first call, never invented, never '
+  + 'reused. Call again with the same arguments. Ignored when the client supports elicitation.',
+);
+
+/** What the fallback binds a token to — recomputed from a fresh read on every call. */
+export interface TokenSubject {
+  /** The draftId / messageId / fileId / eventId / query the dispatch acts on. */
+  target: string;
+  /** A version that rotates on edit: a draft's messageId, an event's etag. */
+  revision?: string;
+  /** Canonical send payload; its SHA-256 is bound into the token. */
+  payload: unknown;
+  /** The complete preview shown to the user. */
+  preview: Record<string, unknown>;
+}
+
+/**
+ * Opt-in second rail for a client that cannot be prompted. `subject` is only
+ * called when the fallback actually runs, so a tool may do an extra read there
+ * without changing the elicitation path at all. It may return an error result
+ * (a failed read), which is passed back unchanged.
+ */
+export interface DispatchTokenFallback {
+  tool: string;
+  account?: string;
+  confirmToken?: string;
+  /** Phase 1's instruction to the model. Defaults to {@link CONFIRM_ACTION_INSTRUCTION}. */
+  instruction?: string;
+  subject: () => TokenSubject | CallToolResult | Promise<TokenSubject | CallToolResult>;
+}
+
+const TOKEN_ERROR_NOTE: Record<Exclude<ConfirmTokenError, 'DRAFT_CHANGED'>, string> = {
+  TOKEN_EXPIRED: 'Nothing was sent or changed: the confirmToken expired. Call again WITHOUT confirmToken for a fresh preview, '
+    + 'and ask the user to approve it again.',
+  TOKEN_REUSED: 'Nothing was sent or changed by this call: this confirmToken was already used, and one approval acts once. '
+    + 'If doing it again is really intended, call again WITHOUT confirmToken and get a new approval.',
+  TOKEN_INVALID: 'Nothing was sent or changed: this confirmToken was not issued by this server for this tool, account and '
+    + 'target (or the server has restarted since). Call again WITHOUT confirmToken for a fresh preview and approval.',
+};
+
+const DRAFT_CHANGED_NOTE = {
+  'message-id-rotated': 'Nothing was sent or changed: the target was edited since the user approved it (a draft\'s '
+    + 'messageId or an event\'s version rotated), so what would happen is not what they saw.',
+  'payload-changed': 'Nothing was sent or changed: what would happen no longer matches what the user approved.',
+} as const;
+
+function isToolResult(value: TokenSubject | CallToolResult): value is CallToolResult {
+  return Array.isArray((value as CallToolResult).content);
+}
+
+function rejection(data: Record<string, unknown>): CallToolResult {
+  return { ...textResult({ status: 'confirmation-rejected', confirmed: false, dispatched: false, ...data }), isError: true };
+}
+
+async function tokenConfirmation(op: string, fallback: DispatchTokenFallback): Promise<CallToolResult | undefined> {
+  const subject = await fallback.subject();
+  if (isToolResult(subject)) return subject;
+  const binding: ConfirmBinding = {
+    tool: fallback.tool,
+    account: fallback.account ?? readEnvVar('GOG_ACCOUNT') ?? '',
+    target: subject.target,
+    ...(subject.revision === undefined ? {} : { revision: subject.revision }),
+    payloadHash: hashSendPayload(subject.payload),
+  };
+  const phaseOne = () => {
+    const { token, expiresAt } = issueConfirmToken(binding);
+    return {
+      action: op,
+      preview: subject.preview,
+      confirmToken: token,
+      expiresAt,
+      ttlSeconds: confirmTokenTtlSeconds(),
+      instruction: fallback.instruction ?? CONFIRM_ACTION_INSTRUCTION,
+    };
+  };
+  if (!fallback.confirmToken) {
+    return textResult({ status: 'confirmation-required', confirmed: false, dispatched: false, ...phaseOne() });
+  }
+  const verdict = verifyConfirmToken(fallback.confirmToken, binding);
+  if (verdict.ok) return undefined;
+  if (verdict.error === 'DRAFT_CHANGED') {
+    return rejection({
+      error: 'DRAFT_CHANGED',
+      reason: verdict.reason,
+      note: `${DRAFT_CHANGED_NOTE[verdict.reason!]} The current preview and a fresh confirmToken are below.`,
+      ...phaseOne(),
+    });
+  }
+  return rejection({ error: verdict.error, action: op, note: TOKEN_ERROR_NOTE[verdict.error] });
+}
+
+/**
+ * The refusal an escape hatch (`gog_<service>_run`, `gog_api_call`) gives for an
+ * action a dedicated tool gates. Without it, the run tool is a way around the
+ * rail: the model forwards the same subcommand and nobody is asked (#400).
+ */
+export function gatedElsewhere(what: string, via: string, does: string, tool: string): string {
+  return `${what} ${does} and is not available through ${via}. Use ${tool}, which asks the user to confirm.`;
+}
+
+/** True when any forwarded token is one of `words` (kong lets flags precede the command word). */
+export function hasCommandWord(args: readonly string[], words: ReadonlySet<string>): string | undefined {
+  return args.find((a) => words.has(a.toLowerCase()));
+}
+
+export interface DispatchConfirmationOptions {
+  /** Stable id of the dispatch, echoed in every result (`gmail.send`, `drive.share`, …). */
+  action: string;
+  /** Heading of the elicitation prompt. */
+  message: string;
+  /** Label beside the prompt's confirmation checkbox. */
+  confirmationLabel: string;
+  /** What the elicitation prompt shows. */
+  details: Record<string, unknown>;
+  /** The way through on a client that cannot be prompted, when there is one. */
+  unsupportedNote?: string;
+  /** Opt-in second rail; omit it and a client that cannot be prompted is always refused. */
+  fallback?: DispatchTokenFallback;
+}
+
+/**
+ * Ask the user before a dispatch. `undefined` means proceed; anything else is
+ * the result to return unchanged.
+ *
+ * Elicitation stays the primary path and is untouched. Only when the caller
+ * declares it cannot be prompted AND a `fallback` is supplied AND
+ * GOG_SEND_CONFIRM_FALLBACK=token does the two-phase token flow run instead of
+ * the refusal; with the env unset, the refusal names that switch.
+ */
+export async function requireDispatchConfirmation(
+  ctx: ServerContext,
+  options: DispatchConfirmationOptions,
+): Promise<InputRequiredResult | CallToolResult | undefined> {
+  const { action, fallback } = options;
+  if (fallback && callerAcceptsFormElicitation(ctx) === false && sendConfirmFallbackEnabled()) {
+    return tokenConfirmation(action, fallback);
+  }
+  const note = fallback
+    ? [options.unsupportedNote, FALLBACK_HINT].filter(Boolean).join(' ')
+    : options.unsupportedNote;
+  return requireConfirmation(ctx, {
+    action,
+    message: options.message,
+    details: options.details,
+    confirmationLabel: options.confirmationLabel,
+    ...(note ? { unsupportedNote: note } : {}),
+  });
+}
+
+// The single place a CallToolResult's text is pulled back out, for the tools
+// here that need to read gog's own JSON before deciding what to preview or
+// log. Mirrors the shape every runOrDiagnose result actually returns
+// (content[0].text); never throws on an unexpected shape.
+export function resultText(result: CallToolResult): string {
+  const first = result.content[0];
+  return first && first.type === 'text' && typeof first.text === 'string' ? first.text : '{}';
+}

package/src/file-roots.ts

@@ -0,0 +1,66 @@
+// Operator-configured confinement for every server-side path a tool accepts
+// (audit SEC-3/SEC-4).
+//
+// `attach`, `localPath`, `file`, `out`, `outDir` and friends are resolved on the
+// machine gog runs on, and the model chooses them. Unconfined, each is a read
+// primitive (attach ~/.ssh/id_rsa, gog's credentials, /proc/<pid>/environ to an
+// email) or a write primitive (drop attacker-chosen attachment bytes on
+// ~/Library/LaunchAgents/x.plist or ~/.zshrc). Every such path must now resolve
+// — through symlinks, via mcp-utils' assertPathWithinRoots — inside one of the
+// directories the operator lists in GOG_FILE_ROOTS, or the server's own private
+// attachment download directory.
+//
+// GOG_FILE_ROOTS is a PATH-style list (':' on POSIX). Unset, it defaults to
+// ~/gogcli-mcp-files: files to attach or upload go there, and exports and
+// downloads with an explicit path must be written there. Set it to a wider
+// directory (e.g. your home) deliberately, not by default.
+
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { assertPathWithinRoots, readEnvVar } from '@chrischall/mcp-utils';
+import { ATTACHMENT_DOWNLOAD_ROOT } from './attachment-root.js';
+
+export const FILE_ROOTS_ENV = 'GOG_FILE_ROOTS';
+
+/** The default root when GOG_FILE_ROOTS is unset. */
+export function defaultFileRoot(): string {
+  return join(homedir(), 'gogcli-mcp-files');
+}
+
+/** The operator's configured roots, or the default one. */
+export function fileRoots(): string[] {
+  const raw = readEnvVar(FILE_ROOTS_ENV);
+  const roots = (raw ?? '').split(delimiter).map((r) => r.trim()).filter(Boolean);
+  return roots.length > 0 ? roots : [defaultFileRoot()];
+}
+
+/**
+ * Require `path` (a model-supplied server path, named `param` in the error) to
+ * lie inside an allowed root. Returns it unchanged. `allowDash` admits gog's
+ * `-` for tools where it means stdout; anywhere else `-` means stdin, which this
+ * server never writes to, so it is refused like any other stray path.
+ */
+export function confinePath(path: string, param: string, opts: { allowDash?: boolean } = {}): string {
+  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;
+}
+
+/** confinePath for every element of an optional list. */
+export function confinePaths(paths: readonly string[] | undefined, param: string): void {
+  for (const path of paths ?? []) confinePath(path, param);
+}
+
+/** For JSON-or-`@file` inputs: confine the path of an `@file` value, pass inline JSON through. */
+export function confineAtFile(value: string, param: string): string {
+  if (value.startsWith('@')) confinePath(value.slice(1), param);
+  return value;
+}