gogcli-mcp 4.2.5 → 4.3.0

package/tests/tools/sheets.test.ts

@@ -3,6 +3,7 @@ import { McpServer } from '@modelcontextprotocol/server';
 import { registerSheetsTools } from '../../src/tools/sheets.js';
 import * as runner from '../../src/runner.js';
 import { createTestHarness } from '@chrischall/mcp-utils/test';
+import { pos } from '../../src/argv.js';
 
 vi.mock('../../src/runner.js');
 
@@ -15,7 +16,7 @@ describe('gog_sheets_get', () => {
     vi.mocked(runner.run).mockResolvedValue('{"values":[["a","b"]]}');
     const harness = await setupHandlers();
     const result = await harness.callTool('gog_sheets_get', { spreadsheetId: 'sid', range: 'Sheet1!A1:B2' });
-    expect(runner.run).toHaveBeenCalledWith(['sheets', 'get', 'sid', 'Sheet1!A1:B2'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['sheets', 'get', pos('sid'), pos('Sheet1!A1:B2')], { account: undefined });
     expect(result.content[0].text).toBe('{"values":[["a","b"]]}');
   });
 
@@ -23,7 +24,7 @@ describe('gog_sheets_get', () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
     await harness.callTool('gog_sheets_get', { spreadsheetId: 'sid', range: 'A1', account: 'other@gmail.com' });
-    expect(runner.run).toHaveBeenCalledWith(['sheets', 'get', 'sid', 'A1'], { account: 'other@gmail.com' });
+    expect(runner.run).toHaveBeenCalledWith(['sheets', 'get', pos('sid'), pos('A1')], { account: 'other@gmail.com' });
   });
 
   it('appends auth list on failure when auth list succeeds', async () => {
@@ -59,7 +60,7 @@ describe('gog_sheets_update', () => {
     const values = [['hello', 'world']];
     await harness.callTool('gog_sheets_update', { spreadsheetId: 'sid', range: 'A1:B1', values });
     expect(runner.run).toHaveBeenCalledWith(
-      ['sheets', 'update', 'sid', 'A1:B1', `--values-json=${JSON.stringify(values)}`],
+      ['sheets', 'update', pos('sid'), pos('A1:B1'), `--values-json=${JSON.stringify(values)}`],
       { account: undefined },
     );
   });
@@ -92,7 +93,7 @@ describe('gog_sheets_update', () => {
     const values = [['x']];
     await harness.callTool('gog_sheets_update', { spreadsheetId: 'sid', range: 'A1', values, dry_run: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['sheets', 'update', 'sid', 'A1', `--values-json=${JSON.stringify(values)}`, '--dry-run'],
+      ['sheets', 'update', pos('sid'), pos('A1'), `--values-json=${JSON.stringify(values)}`, '--dry-run'],
       { account: undefined },
     );
   });
@@ -110,7 +111,7 @@ describe('gog_sheets_update', () => {
     const values = [['=1+1']];
     await harness.callTool('gog_sheets_update', { spreadsheetId: 'sid', range: 'A1', values, fail_on_formula_error: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['sheets', 'update', 'sid', 'A1', `--values-json=${JSON.stringify(values)}`, '--fail-on-formula-error'],
+      ['sheets', 'update', pos('sid'), pos('A1'), `--values-json=${JSON.stringify(values)}`, '--fail-on-formula-error'],
       { account: undefined },
     );
   });
@@ -125,7 +126,7 @@ describe('gog_sheets_update fail_if_not_empty guard', () => {
     });
     // Only the read happened — no update call.
     expect(runner.run).toHaveBeenCalledTimes(1);
-    expect(runner.run).toHaveBeenCalledWith(['sheets', 'get', 'sid', 'A1:A1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['sheets', 'get', pos('sid'), pos('A1:A1')], { account: undefined });
     expect(result.content[0].text).toContain('Write aborted');
     expect(result.content[0].text).toContain('A1:A1');
     expect(result.content[0].text).toContain('1 cell');
@@ -142,7 +143,7 @@ describe('gog_sheets_update fail_if_not_empty guard', () => {
     });
     expect(runner.run).toHaveBeenCalledTimes(2);
     expect(vi.mocked(runner.run).mock.calls[1]![0]).toEqual(
-      ['sheets', 'update', 'sid', 'A1', `--values-json=${JSON.stringify(values)}`],
+      ['sheets', 'update', pos('sid'), pos('A1'), `--values-json=${JSON.stringify(values)}`],
     );
     expect(result.content[0].text).toBe('{"updatedCells":1}');
   });
@@ -156,7 +157,7 @@ describe('gog_sheets_update fail_if_not_empty guard', () => {
       spreadsheetId: 'sid', range: 'Sheet1!A1',
       values: [['a', 'b'], ['c', 'd'], ['e', 'f']], fail_if_not_empty: true,
     });
-    expect(vi.mocked(runner.run).mock.calls[0]![0]).toEqual(['sheets', 'get', 'sid', 'Sheet1!A1:B3']);
+    expect(vi.mocked(runner.run).mock.calls[0]![0]).toEqual(['sheets', 'get', pos('sid'), pos('Sheet1!A1:B3')]);
   });
 
   it('aborts without writing and diagnoses the error when the verification read fails', async () => {
@@ -234,7 +235,7 @@ describe('gog_sheets_append', () => {
     const values = [['r1c1', 'r1c2'], ['r2c1', 'r2c2']];
     await harness.callTool('gog_sheets_append', { spreadsheetId: 'sid', range: 'Sheet1!A:B', values });
     expect(runner.run).toHaveBeenCalledWith(
-      ['sheets', 'append', 'sid', 'Sheet1!A:B', `--values-json=${JSON.stringify(values)}`],
+      ['sheets', 'append', pos('sid'), pos('Sheet1!A:B'), `--values-json=${JSON.stringify(values)}`],
       { account: undefined },
     );
   });
@@ -252,7 +253,7 @@ describe('gog_sheets_append', () => {
     const values = [['x']];
     await harness.callTool('gog_sheets_append', { spreadsheetId: 'sid', range: 'Sheet1!A:A', values, dry_run: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['sheets', 'append', 'sid', 'Sheet1!A:A', `--values-json=${JSON.stringify(values)}`, '--dry-run'],
+      ['sheets', 'append', pos('sid'), pos('Sheet1!A:A'), `--values-json=${JSON.stringify(values)}`, '--dry-run'],
       { account: undefined },
     );
   });
@@ -263,7 +264,7 @@ describe('gog_sheets_clear', () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
     await harness.callTool('gog_sheets_clear', { spreadsheetId: 'sid', range: 'Sheet1!A1:Z100' });
-    expect(runner.run).toHaveBeenCalledWith(['sheets', 'clear', 'sid', 'Sheet1!A1:Z100'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['sheets', 'clear', pos('sid'), pos('Sheet1!A1:Z100')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -278,7 +279,7 @@ describe('gog_sheets_clear', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_sheets_clear', { spreadsheetId: 'sid', range: 'Sheet1!A1:Z100', dry_run: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['sheets', 'clear', 'sid', 'Sheet1!A1:Z100', '--dry-run'],
+      ['sheets', 'clear', pos('sid'), pos('Sheet1!A1:Z100'), '--dry-run'],
       { account: undefined },
     );
   });
@@ -300,7 +301,7 @@ describe('gog_sheets_metadata', () => {
     vi.mocked(runner.run).mockResolvedValue('{"title":"My Sheet","sheets":[{"title":"Sheet1"}]}');
     const harness = await setupHandlers();
     const result = await harness.callTool('gog_sheets_metadata', { spreadsheetId: 'sid' });
-    expect(runner.run).toHaveBeenCalledWith(['sheets', 'metadata', 'sid'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['sheets', 'metadata', pos('sid')], { account: undefined });
     expect(result.content[0].text).toContain('My Sheet');
   });
 
@@ -317,7 +318,7 @@ describe('gog_sheets_create', () => {
     vi.mocked(runner.run).mockResolvedValue('{"spreadsheetId":"newid","title":"Budget 2026"}');
     const harness = await setupHandlers();
     await harness.callTool('gog_sheets_create', { title: 'Budget 2026' });
-    expect(runner.run).toHaveBeenCalledWith(['sheets', 'create', 'Budget 2026'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['sheets', 'create', pos('Budget 2026')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -333,7 +334,7 @@ describe('gog_sheets_find_replace', () => {
     vi.mocked(runner.run).mockResolvedValue('{"occurrencesChanged":3}');
     const harness = await setupHandlers();
     await harness.callTool('gog_sheets_find_replace', { spreadsheetId: 'sid', find: 'foo', replace: 'bar' });
-    expect(runner.run).toHaveBeenCalledWith(['sheets', 'find-replace', 'sid', 'foo', 'bar'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['sheets', 'find-replace', pos('sid'), pos('foo'), pos('bar')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {

package/tests/tools/slides.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { registerSlidesTools } from '../../src/tools/slides.js';
 import * as runner from '../../src/runner.js';
 import { createTestHarness } from '@chrischall/mcp-utils/test';
+import { pos } from '../../src/argv.js';
 
 vi.mock('../../src/runner.js');
 
@@ -14,7 +15,7 @@ describe('gog_slides_export', () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
     await harness.callTool('gog_slides_export', { presentationId: 'p1' });
-    expect(runner.run).toHaveBeenCalledWith(['slides', 'export', 'p1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['slides', 'export', pos('p1')], { account: undefined });
   });
 
   it('passes --out and --format when provided', async () => {
@@ -22,7 +23,7 @@ describe('gog_slides_export', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_slides_export', { presentationId: 'p1', out: '/tmp/deck.pdf', format: 'pdf' });
     expect(runner.run).toHaveBeenCalledWith(
-      ['slides', 'export', 'p1', '--out=/tmp/deck.pdf', '--format=pdf'],
+      ['slides', 'export', pos('p1'), '--out=/tmp/deck.pdf', '--format=pdf'],
       { account: undefined },
     );
   });
@@ -32,7 +33,7 @@ describe('gog_slides_export', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_slides_export', { presentationId: 'p1', out: '/tmp/deck.pptx', overwrite: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['slides', 'export', 'p1', '--out=/tmp/deck.pptx', '--overwrite'],
+      ['slides', 'export', pos('p1'), '--out=/tmp/deck.pptx', '--overwrite'],
       { account: undefined },
     );
   });
@@ -50,7 +51,7 @@ describe('gog_slides_info', () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
     await harness.callTool('gog_slides_info', { presentationId: 'p1' });
-    expect(runner.run).toHaveBeenCalledWith(['slides', 'info', 'p1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['slides', 'info', pos('p1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -66,7 +67,7 @@ describe('gog_slides_create', () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
     await harness.callTool('gog_slides_create', { title: 'Deck' });
-    expect(runner.run).toHaveBeenCalledWith(['slides', 'create', 'Deck'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['slides', 'create', pos('Deck')], { account: undefined });
   });
 
   it('passes --parent and --template when provided', async () => {
@@ -74,7 +75,7 @@ describe('gog_slides_create', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_slides_create', { title: 'Deck', parent: 'folder1', template: 'tpl1' });
     expect(runner.run).toHaveBeenCalledWith(
-      ['slides', 'create', 'Deck', '--parent=folder1', '--template=tpl1'],
+      ['slides', 'create', pos('Deck'), '--parent=folder1', '--template=tpl1'],
       { account: undefined },
     );
   });
@@ -93,7 +94,7 @@ describe('gog_slides_copy', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_slides_copy', { presentationId: 'p1', title: 'Copy' });
     expect(runner.run).toHaveBeenCalledWith(
-      ['slides', 'copy', 'p1', 'Copy'],
+      ['slides', 'copy', pos('p1'), pos('Copy')],
       { account: undefined },
     );
   });
@@ -103,7 +104,7 @@ describe('gog_slides_copy', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_slides_copy', { presentationId: 'p1', title: 'Copy', parent: 'folder1' });
     expect(runner.run).toHaveBeenCalledWith(
-      ['slides', 'copy', 'p1', 'Copy', '--parent=folder1'],
+      ['slides', 'copy', pos('p1'), pos('Copy'), '--parent=folder1'],
       { account: undefined },
     );
   });
@@ -121,7 +122,7 @@ describe('gog_slides_list_slides', () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
     await harness.callTool('gog_slides_list_slides', { presentationId: 'p1' });
-    expect(runner.run).toHaveBeenCalledWith(['slides', 'list-slides', 'p1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['slides', 'list-slides', pos('p1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -138,7 +139,7 @@ describe('gog_slides_read_slide', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_slides_read_slide', { presentationId: 'p1', slideId: 's1' });
     expect(runner.run).toHaveBeenCalledWith(
-      ['slides', 'read-slide', 'p1', 's1'],
+      ['slides', 'read-slide', pos('p1'), pos('s1')],
       { account: undefined },
     );
   });
@@ -148,7 +149,7 @@ describe('gog_slides_read_slide', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_slides_read_slide', { presentationId: 'p1', slideId: 's1', detail: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['slides', 'read-slide', 'p1', 's1', '--detail'],
+      ['slides', 'read-slide', pos('p1'), pos('s1'), '--detail'],
       { account: undefined },
     );
   });
@@ -176,3 +177,38 @@ describe('gog_slides_run', () => {
     expect(result.content[0].text).toBe('Error: Run failed');
   });
 });
+
+// SEC-3/SEC-4: every model-supplied server path must resolve inside an
+// operator-configured root (GOG_FILE_ROOTS). The suite runs with '/' so the
+// arg-shape tests can use any path; these narrow it.
+async function withFileRoots<T>(roots: string, fn: () => Promise<T>): Promise<T> {
+  const prev = process.env.GOG_FILE_ROOTS;
+  process.env.GOG_FILE_ROOTS = roots;
+  try {
+    return await fn();
+  } finally {
+    process.env.GOG_FILE_ROOTS = prev;
+  }
+}
+
+describe('gog_slides_export — writes to disk', () => {
+  it('refuses an out path outside GOG_FILE_ROOTS', async () => {
+    const harness = await setupHandlers();
+    const result = await withFileRoots('/srv/gog-files', () => harness.callTool('gog_slides_export', {
+      presentationId: 'p1', out: '/Users/me/.zshrc', overwrite: true,
+    }));
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('out "/Users/me/.zshrc" is outside');
+    expect(runner.run).not.toHaveBeenCalled();
+  });
+
+  // SEC-4: clients auto-approve readOnlyHint tools; this one writes a file and
+  // can overwrite one, so the client must be allowed to ask.
+  it('is not advertised as read-only, and is marked destructive', async () => {
+    const harness = await setupHandlers();
+    const { tools } = await harness.client.listTools();
+    const tool = tools.find((t) => t.name === 'gog_slides_export')!;
+    expect(tool.annotations?.readOnlyHint).not.toBe(true);
+    expect(tool.annotations?.destructiveHint).toBe(true);
+  });
+});

package/tests/tools/tasks.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { registerTasksTools } from '../../src/tools/tasks.js';
 import * as runner from '../../src/runner.js';
 import { createTestHarness } from '@chrischall/mcp-utils/test';
+import { pos } from '../../src/argv.js';
 
 vi.mock('../../src/runner.js');
 
@@ -30,7 +31,7 @@ describe('gog_tasks_list', () => {
     vi.mocked(runner.run).mockResolvedValue('{"items":[]}');
     const harness = await setupHandlers();
     await harness.callTool('gog_tasks_list', { tasklistId: 'list1' });
-    expect(runner.run).toHaveBeenCalledWith(['tasks', 'list', 'list1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['tasks', 'list', pos('list1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -46,7 +47,7 @@ describe('gog_tasks_get', () => {
     vi.mocked(runner.run).mockResolvedValue('{"id":"task1"}');
     const harness = await setupHandlers();
     await harness.callTool('gog_tasks_get', { tasklistId: 'list1', taskId: 'task1' });
-    expect(runner.run).toHaveBeenCalledWith(['tasks', 'get', 'list1', 'task1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['tasks', 'get', pos('list1'), pos('task1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -63,7 +64,7 @@ describe('gog_tasks_add', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_tasks_add', { tasklistId: 'list1', title: 'Buy milk' });
     expect(runner.run).toHaveBeenCalledWith(
-      ['tasks', 'add', 'list1', '--title=Buy milk'],
+      ['tasks', 'add', pos('list1'), '--title=Buy milk'],
       { account: undefined },
     );
   });
@@ -73,7 +74,7 @@ describe('gog_tasks_add', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_tasks_add', { tasklistId: 'list1', title: 'Buy milk', notes: 'Whole milk', due: '2026-04-20' });
     expect(runner.run).toHaveBeenCalledWith(
-      ['tasks', 'add', 'list1', '--title=Buy milk', '--notes=Whole milk', '--due=2026-04-20'],
+      ['tasks', 'add', pos('list1'), '--title=Buy milk', '--notes=Whole milk', '--due=2026-04-20'],
       { account: undefined },
     );
   });
@@ -91,7 +92,7 @@ describe('gog_tasks_done', () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
     await harness.callTool('gog_tasks_done', { tasklistId: 'list1', taskId: 'task1' });
-    expect(runner.run).toHaveBeenCalledWith(['tasks', 'done', 'list1', 'task1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['tasks', 'done', pos('list1'), pos('task1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -107,7 +108,7 @@ describe('gog_tasks_delete', () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
     await harness.callTool('gog_tasks_delete', { tasklistId: 'list1', taskId: 'task1' });
-    expect(runner.run).toHaveBeenCalledWith(['tasks', 'delete', 'list1', 'task1', '--force'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['tasks', 'delete', pos('list1'), pos('task1'), '--force'], { account: undefined });
   });
 
   it('returns error text on failure', async () => {

package/tests/tools/utils.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import * as runner from '../../src/runner.js';
 import { runOrDiagnose, pushPaginationFlags, formatAccountList, formatAuthHealth } from '../../src/tools/utils.js';
+import { pos } from '../../src/argv.js';
 
 // PARTIAL mock: only `run` is stubbed; everything else stays real.
 vi.mock('../../src/runner.js', async (importOriginal) => ({
@@ -51,7 +52,7 @@ describe('formatAccountList', () => {
         email: 'chris.c.hall@gmail.com',
         subject: '109876543210987654321',
         client: 'default',
-        services: ['gmail', 'drive'],
+        services: ['gmail', pos('drive')],
         scopes: ['https://www.googleapis.com/auth/gmail.modify', 'https://www.googleapis.com/auth/drive'],
         created_at: '2026-01-02T03:04:05Z',
       },
@@ -94,7 +95,7 @@ describe('formatAccountList', () => {
 describe('runOrDiagnose', () => {
   it('returns output text on success (not flagged as an error)', async () => {
     vi.mocked(runner.run).mockResolvedValue('{"ok":true}');
-    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    const result = await runOrDiagnose(['docs', 'cat', pos('abc')], {});
     expect(result.content[0].text).toBe('{"ok":true}');
     expect(result.isError).toBeUndefined();
   });
@@ -106,7 +107,7 @@ describe('runOrDiagnose', () => {
   it('leaves a lossless response byte-for-byte untouched', async () => {
     const raw = '{\n  "id": "m1",\n  "internalDate": "1785209760000"\n}';
     vi.mocked(runner.run).mockResolvedValue(raw);
-    const result = await runOrDiagnose(['gmail', 'raw', 'm1'], { lossless: true });
+    const result = await runOrDiagnose(['gmail', 'raw', pos('m1')], { lossless: true });
     expect(result.content[0].text).toBe(raw);
   });
 
@@ -182,7 +183,7 @@ describe('runOrDiagnose', () => {
   it('does NOT minify a lossless response', async () => {
     const raw = '{\n  "id": "m1"\n}';
     vi.mocked(runner.run).mockResolvedValue(raw);
-    const result = await runOrDiagnose(['gmail', 'raw', 'm1'], { lossless: true });
+    const result = await runOrDiagnose(['gmail', 'raw', pos('m1')], { lossless: true });
     expect(result.content[0].text).toBe(raw);
   });
 
@@ -230,7 +231,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run).mockResolvedValue(
       '{\n  "id": "f1",\n  "thumbnailLink": "https://lh3.googleusercontent.com/x=s220",\n  "webViewLink": "https://docs.google.com/d/f1"\n}',
     );
-    const result = await runOrDiagnose(['drive', 'get', 'f1'], { stripMedia: true });
+    const result = await runOrDiagnose(['drive', 'get', pos('f1')], { stripMedia: true });
     expect(result.content[0].text).toBe('{"id":"f1","webViewLink":"https://docs.google.com/d/f1"}');
   });
 
@@ -240,14 +241,14 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run).mockResolvedValue(
       JSON.stringify({ files: [{ id: 'f1', hasThumbnail: false, thumbnailLink: 'https://x/y=s220', webViewLink: 'https://docs/f1' }] }),
     );
-    const result = await runOrDiagnose(['drive', 'search', 'q'], { stripMedia: true });
+    const result = await runOrDiagnose(['drive', 'search', pos('q')], { stripMedia: true });
     const parsed = JSON.parse(result.content[0].text as string);
     expect(parsed.files[0]).toEqual({ id: 'f1', hasThumbnail: false, webViewLink: 'https://docs/f1' });
   });
 
   it('does not strip media unless asked', async () => {
     vi.mocked(runner.run).mockResolvedValue('{"thumbnailLink":"https://x/y=s220"}');
-    const result = await runOrDiagnose(['drive', 'get', 'f1'], {});
+    const result = await runOrDiagnose(['drive', 'get', pos('f1')], {});
     expect(result.content[0].text).toBe('{"thumbnailLink":"https://x/y=s220"}');
   });
 
@@ -263,7 +264,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Doc not found'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    const result = await runOrDiagnose(['docs', 'cat', pos('abc')], {});
     expect(result.content[0].text).toBe(
       'Error: Doc not found\n\nConfigured accounts:\nuser@gmail.com',
     );
@@ -284,7 +285,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('refusing to delete gmail draft r123 without --force (non-interactive)'))
       .mockResolvedValueOnce(authListJson);
-    const result = await runOrDiagnose(['gmail', 'drafts', 'delete', 'r123'], {});
+    const result = await runOrDiagnose(['gmail', 'drafts', 'delete', pos('r123')], {});
     const text = result.content[0].text;
     expect(text).toContain('Configured accounts:\nchris.c.hall@gmail.com');
     expect(text).not.toContain('scopes');
@@ -297,7 +298,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Doc not found'))
       .mockResolvedValueOnce('{"accounts":[]}');
-    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    const result = await runOrDiagnose(['docs', 'cat', pos('abc')], {});
     expect(result.content[0].text).toBe('Error: Doc not found\n\nConfigured accounts:\n(none)');
   });
 
@@ -305,7 +306,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Request failed with status 401'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['docs', 'comments', 'list', 'abc'], {});
+    const result = await runOrDiagnose(['docs', 'comments', 'list', pos('abc')], {});
     expect(result.content[0].text).toContain('Error: Request failed with status 401');
     expect(result.content[0].text).toContain('Configured accounts:\nuser@gmail.com');
     expect(result.content[0].text).toContain('gog_auth_add');
@@ -315,7 +316,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('unauthorized access'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    const result = await runOrDiagnose(['docs', 'cat', pos('abc')], {});
     expect(result.content[0].text).toContain('gog_auth_add');
   });
 
@@ -323,7 +324,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('token has been expired or revoked'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    const result = await runOrDiagnose(['docs', 'cat', pos('abc')], {});
     expect(result.content[0].text).toContain('gog_auth_add');
   });
 
@@ -331,7 +332,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('invalid_grant'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    const result = await runOrDiagnose(['docs', 'cat', pos('abc')], {});
     expect(result.content[0].text).toContain('gog_auth_add');
   });
 
@@ -346,7 +347,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('429 rateLimitExceeded: the access token expired mid-request, retry'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['sheets', 'get', 'A1'], {});
+    const result = await runOrDiagnose(['sheets', 'get', pos('A1')], {});
     const text = result.content[0].text as string;
     expect(text).toContain('often transient');
     expect(text).not.toContain('gog_auth_add');
@@ -359,7 +360,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('401 unauthorized (quota project unset)'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['sheets', 'get', 'A1'], {});
+    const result = await runOrDiagnose(['sheets', 'get', pos('A1')], {});
     expect(result.content[0].text).toContain('gog_auth_add');
   });
 
@@ -375,7 +376,7 @@ describe('runOrDiagnose', () => {
         new Error('page token accepted; the requested export link has expired and must be regenerated'),
       )
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['drive', 'export', 'abc'], {});
+    const result = await runOrDiagnose(['drive', pos('export'), pos('abc')], {});
     expect(result.content[0].text).not.toContain('gog_auth_add');
   });
 
@@ -383,7 +384,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('oauth2: "invalid_grant" "Token has been expired or revoked."'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['gmail', 'search', 'is:unread'], {});
+    const result = await runOrDiagnose(['gmail', 'search', pos('is:unread')], {});
     const text = result.content[0].text as string;
     // plain-English cause
     expect(text).toContain('7-day');
@@ -398,7 +399,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Request failed with status 401'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    const result = await runOrDiagnose(['docs', 'cat', pos('abc')], {});
     const text = result.content[0].text as string;
     expect(text).toContain('gog_auth_add');
     expect(text).not.toContain('In production');
@@ -408,7 +409,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Request failed with status 401'))
       .mockRejectedValueOnce(new Error('auth list failed'));
-    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    const result = await runOrDiagnose(['docs', 'cat', pos('abc')], {});
     expect(result.content[0].text).toContain('Error: Request failed with status 401');
     expect(result.content[0].text).toContain('gog_auth_add');
     expect(result.content[0].text).not.toContain('Configured accounts');
@@ -418,7 +419,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Doc not found'))
       .mockRejectedValueOnce(new Error('auth list failed'));
-    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    const result = await runOrDiagnose(['docs', 'cat', pos('abc')], {});
     expect(result.content[0].text).toBe('Error: Doc not found');
     expect(result.isError).toBe(true);
     expect(result.content[0].text).not.toContain('gog_auth_add');
@@ -428,7 +429,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Request failed with status 429'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['sheets', 'update', 'abc', 'A1'], {});
+    const result = await runOrDiagnose(['sheets', 'update', pos('abc'), pos('A1')], {});
     expect(result.content[0].text).toContain('transient');
     expect(result.content[0].text).toContain('Retry');
   });
@@ -439,7 +440,7 @@ describe('runOrDiagnose', () => {
       vi.mocked(runner.run)
         .mockRejectedValueOnce(new Error(`Request failed with status ${status}`))
         .mockResolvedValueOnce('user@gmail.com');
-      const result = await runOrDiagnose(['sheets', 'update', 'abc', 'A1'], {});
+      const result = await runOrDiagnose(['sheets', 'update', pos('abc'), pos('A1')], {});
       expect(result.content[0].text, `status ${status}`).toContain('transient');
     }
   });
@@ -450,7 +451,7 @@ describe('runOrDiagnose', () => {
       vi.mocked(runner.run)
         .mockRejectedValueOnce(new Error(msg))
         .mockResolvedValueOnce('user@gmail.com');
-      const result = await runOrDiagnose(['sheets', 'update', 'abc', 'A1'], {});
+      const result = await runOrDiagnose(['sheets', 'update', pos('abc'), pos('A1')], {});
       expect(result.content[0].text, msg).toContain('transient');
     }
   });
@@ -459,7 +460,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('DEADLINE_EXCEEDED: context deadline exceeded'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['sheets', 'update', 'abc', 'A1'], {});
+    const result = await runOrDiagnose(['sheets', 'update', pos('abc'), pos('A1')], {});
     expect(result.content[0].text).toContain('transient');
   });
 
@@ -467,7 +468,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Request failed with status 404'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['sheets', 'get', 'abc', 'A1'], {});
+    const result = await runOrDiagnose(['sheets', 'get', pos('abc'), pos('A1')], {});
     expect(result.content[0].text).not.toContain('transient');
   });
 
@@ -475,7 +476,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Request failed with status 401'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    const result = await runOrDiagnose(['docs', 'cat', pos('abc')], {});
     expect(result.content[0].text).toContain('gog_auth_add');
     expect(result.content[0].text).not.toContain('transient');
   });
@@ -484,7 +485,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Request failed with status 503'))
       .mockRejectedValueOnce(new Error('auth list failed'));
-    const result = await runOrDiagnose(['sheets', 'update', 'abc', 'A1'], {});
+    const result = await runOrDiagnose(['sheets', 'update', pos('abc'), pos('A1')], {});
     expect(result.content[0].text).toContain('transient');
     expect(result.content[0].text).not.toContain('Configured accounts');
   });
@@ -493,7 +494,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Range (Sheet1!AP1:AW1) exceeds grid limits. Max rows: 1000, max columns: 41'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['sheets', 'update', 'abc', 'AP1'], {});
+    const result = await runOrDiagnose(['sheets', 'update', pos('abc'), pos('AP1')], {});
     expect(result.content[0].text).toContain('exceeds grid limits');
     expect(result.content[0].text).toContain('gog_sheets_insert');
   });
@@ -502,7 +503,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Spreadsheet not found'))
       .mockResolvedValueOnce('user@gmail.com');
-    const result = await runOrDiagnose(['sheets', 'update', 'abc', 'A1'], {});
+    const result = await runOrDiagnose(['sheets', 'update', pos('abc'), pos('A1')], {});
     expect(result.content[0].text).not.toContain('gog_sheets_insert');
   });
 
@@ -510,7 +511,7 @@ describe('runOrDiagnose', () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('exceeds grid limits. Max rows: 1000, max columns: 41'))
       .mockRejectedValueOnce(new Error('auth list failed'));
-    const result = await runOrDiagnose(['sheets', 'update', 'abc', 'A1'], {});
+    const result = await runOrDiagnose(['sheets', 'update', pos('abc'), pos('A1')], {});
     expect(result.content[0].text).toContain('gog_sheets_insert');
     expect(result.content[0].text).not.toContain('Configured accounts');
   });

package/vitest.config.ts

@@ -20,6 +20,11 @@ export default defineConfig({
       GOG_ACCOUNT: '',
       GOG_PATH: '',
       GOG_READONLY: '',
+      // The arg-shape tests pass arbitrary server paths (/tmp/shot.png,
+      // /path/to/file); confinement is exercised explicitly by the tests that
+      // narrow GOG_FILE_ROOTS themselves (tests/file-roots.test.ts and the
+      // per-tool "refuses a path outside" cases).
+      GOG_FILE_ROOTS: '/',
     },
     coverage: {
       provider: 'v8',