gogcli-mcp 4.2.5 → 4.3.0

package/tests/tools/classroom.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { registerClassroomTools } from '../../src/tools/classroom.js';
 import * as runner from '../../src/runner.js';
 import { createTestHarness, type TestHarness } from '@chrischall/mcp-utils/test';
+import { pos } from '../../src/argv.js';
 
 vi.mock('../../src/runner.js');
 
@@ -51,7 +52,7 @@ describe('gog_classroom_courses_list', () => {
 describe('gog_classroom_courses_get', () => {
   it('calls run with courseId', async () => {
     await harness.callTool('gog_classroom_courses_get', { courseId: 'c1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'courses', 'get', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'courses', 'get', pos('c1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -64,20 +65,20 @@ describe('gog_classroom_courses_get', () => {
 describe('gog_classroom_students_list', () => {
   it('calls run with courseId only', async () => {
     await harness.callTool('gog_classroom_students_list', { courseId: 'c1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'students', 'list', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'students', 'list', pos('c1')], { account: undefined });
   });
 
   it('passes all listing flags', async () => {
     await harness.callTool('gog_classroom_students_list', { courseId: 'c1', max: 20, page: 'tok', all: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['classroom', 'students', 'list', 'c1', '--max=20', '--page=tok', '--all'],
+      ['classroom', 'students', 'list', pos('c1'), '--max=20', '--page=tok', '--all'],
       { account: undefined },
     );
   });
 
   it('omits --all when false', async () => {
     await harness.callTool('gog_classroom_students_list', { courseId: 'c1', all: false });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'students', 'list', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'students', 'list', pos('c1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -90,7 +91,7 @@ describe('gog_classroom_students_list', () => {
 describe('gog_classroom_students_get', () => {
   it('calls run with courseId and userId', async () => {
     await harness.callTool('gog_classroom_students_get', { courseId: 'c1', userId: 'u1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'students', 'get', 'c1', 'u1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'students', 'get', pos('c1'), pos('u1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -103,20 +104,20 @@ describe('gog_classroom_students_get', () => {
 describe('gog_classroom_teachers_list', () => {
   it('calls run with courseId only', async () => {
     await harness.callTool('gog_classroom_teachers_list', { courseId: 'c1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'teachers', 'list', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'teachers', 'list', pos('c1')], { account: undefined });
   });
 
   it('passes all listing flags', async () => {
     await harness.callTool('gog_classroom_teachers_list', { courseId: 'c1', max: 20, page: 'tok', all: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['classroom', 'teachers', 'list', 'c1', '--max=20', '--page=tok', '--all'],
+      ['classroom', 'teachers', 'list', pos('c1'), '--max=20', '--page=tok', '--all'],
       { account: undefined },
     );
   });
 
   it('omits --all when false', async () => {
     await harness.callTool('gog_classroom_teachers_list', { courseId: 'c1', all: false });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'teachers', 'list', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'teachers', 'list', pos('c1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -129,7 +130,7 @@ describe('gog_classroom_teachers_list', () => {
 describe('gog_classroom_teachers_get', () => {
   it('calls run with courseId and userId', async () => {
     await harness.callTool('gog_classroom_teachers_get', { courseId: 'c1', userId: 'u1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'teachers', 'get', 'c1', 'u1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'teachers', 'get', pos('c1'), pos('u1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -142,20 +143,20 @@ describe('gog_classroom_teachers_get', () => {
 describe('gog_classroom_roster', () => {
   it('calls run with courseId only', async () => {
     await harness.callTool('gog_classroom_roster', { courseId: 'c1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'roster', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'roster', pos('c1')], { account: undefined });
   });
 
   it('passes all flags', async () => {
     await harness.callTool('gog_classroom_roster', { courseId: 'c1', students: true, teachers: true, max: 50, page: 'tok', all: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['classroom', 'roster', 'c1', '--students', '--teachers', '--max=50', '--page=tok', '--all'],
+      ['classroom', 'roster', pos('c1'), '--students', '--teachers', '--max=50', '--page=tok', '--all'],
       { account: undefined },
     );
   });
 
   it('omits boolean flags when false', async () => {
     await harness.callTool('gog_classroom_roster', { courseId: 'c1', students: false, teachers: false, all: false });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'roster', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'roster', pos('c1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -168,7 +169,7 @@ describe('gog_classroom_roster', () => {
 describe('gog_classroom_coursework_list', () => {
   it('calls run with courseId only', async () => {
     await harness.callTool('gog_classroom_coursework_list', { courseId: 'c1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'coursework', 'list', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'coursework', 'list', pos('c1')], { account: undefined });
   });
 
   it('passes all listing flags', async () => {
@@ -183,14 +184,14 @@ describe('gog_classroom_coursework_list', () => {
       scanPages: 5,
     });
     expect(runner.run).toHaveBeenCalledWith(
-      ['classroom', 'coursework', 'list', 'c1', '--state=PUBLISHED', '--topic=t1', '--order-by=updateTime desc', '--max=50', '--page=tok', '--all', '--scan-pages=5'],
+      ['classroom', 'coursework', 'list', pos('c1'), '--state=PUBLISHED', '--topic=t1', '--order-by=updateTime desc', '--max=50', '--page=tok', '--all', '--scan-pages=5'],
       { account: undefined },
     );
   });
 
   it('omits --all when false', async () => {
     await harness.callTool('gog_classroom_coursework_list', { courseId: 'c1', all: false });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'coursework', 'list', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'coursework', 'list', pos('c1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -203,7 +204,7 @@ describe('gog_classroom_coursework_list', () => {
 describe('gog_classroom_coursework_get', () => {
   it('calls run with courseId and courseworkId', async () => {
     await harness.callTool('gog_classroom_coursework_get', { courseId: 'c1', courseworkId: 'w1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'coursework', 'get', 'c1', 'w1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'coursework', 'get', pos('c1'), pos('w1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -216,7 +217,7 @@ describe('gog_classroom_coursework_get', () => {
 describe('gog_classroom_submissions_list', () => {
   it('calls run with ids only', async () => {
     await harness.callTool('gog_classroom_submissions_list', { courseId: 'c1', courseworkId: 'w1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'list', 'c1', 'w1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'list', pos('c1'), pos('w1')], { account: undefined });
   });
 
   it('passes all listing flags', async () => {
@@ -231,14 +232,14 @@ describe('gog_classroom_submissions_list', () => {
       all: true,
     });
     expect(runner.run).toHaveBeenCalledWith(
-      ['classroom', 'submissions', 'list', 'c1', 'w1', '--state=TURNED_IN', '--late=late', '--user=u1', '--max=20', '--page=tok', '--all'],
+      ['classroom', 'submissions', 'list', pos('c1'), pos('w1'), '--state=TURNED_IN', '--late=late', '--user=u1', '--max=20', '--page=tok', '--all'],
       { account: undefined },
     );
   });
 
   it('omits --all when false', async () => {
     await harness.callTool('gog_classroom_submissions_list', { courseId: 'c1', courseworkId: 'w1', all: false });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'list', 'c1', 'w1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'list', pos('c1'), pos('w1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -251,7 +252,7 @@ describe('gog_classroom_submissions_list', () => {
 describe('gog_classroom_submissions_get', () => {
   it('calls run with all three ids', async () => {
     await harness.callTool('gog_classroom_submissions_get', { courseId: 'c1', courseworkId: 'w1', submissionId: 's1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'get', 'c1', 'w1', 's1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'get', pos('c1'), pos('w1'), pos('s1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -264,13 +265,13 @@ describe('gog_classroom_submissions_get', () => {
 describe('gog_classroom_submissions_grade', () => {
   it('calls run with ids only', async () => {
     await harness.callTool('gog_classroom_submissions_grade', { courseId: 'c1', courseworkId: 'w1', submissionId: 's1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'grade', 'c1', 'w1', 's1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'grade', pos('c1'), pos('w1'), pos('s1')], { account: undefined });
   });
 
   it('passes --draft and --assigned when provided', async () => {
     await harness.callTool('gog_classroom_submissions_grade', { courseId: 'c1', courseworkId: 'w1', submissionId: 's1', draft: '90', assigned: '95' });
     expect(runner.run).toHaveBeenCalledWith(
-      ['classroom', 'submissions', 'grade', 'c1', 'w1', 's1', '--draft=90', '--assigned=95'],
+      ['classroom', 'submissions', 'grade', pos('c1'), pos('w1'), pos('s1'), '--draft=90', '--assigned=95'],
       { account: undefined },
     );
   });
@@ -285,7 +286,7 @@ describe('gog_classroom_submissions_grade', () => {
 describe('gog_classroom_submissions_return', () => {
   it('calls run with ids', async () => {
     await harness.callTool('gog_classroom_submissions_return', { courseId: 'c1', courseworkId: 'w1', submissionId: 's1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'return', 'c1', 'w1', 's1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'return', pos('c1'), pos('w1'), pos('s1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -298,7 +299,7 @@ describe('gog_classroom_submissions_return', () => {
 describe('gog_classroom_submissions_turn_in', () => {
   it('calls run with ids', async () => {
     await harness.callTool('gog_classroom_submissions_turn_in', { courseId: 'c1', courseworkId: 'w1', submissionId: 's1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'turn-in', 'c1', 'w1', 's1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'turn-in', pos('c1'), pos('w1'), pos('s1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -311,7 +312,7 @@ describe('gog_classroom_submissions_turn_in', () => {
 describe('gog_classroom_submissions_reclaim', () => {
   it('calls run with ids', async () => {
     await harness.callTool('gog_classroom_submissions_reclaim', { courseId: 'c1', courseworkId: 'w1', submissionId: 's1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'reclaim', 'c1', 'w1', 's1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'submissions', 'reclaim', pos('c1'), pos('w1'), pos('s1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -324,20 +325,20 @@ describe('gog_classroom_submissions_reclaim', () => {
 describe('gog_classroom_announcements_list', () => {
   it('calls run with courseId only', async () => {
     await harness.callTool('gog_classroom_announcements_list', { courseId: 'c1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'announcements', 'list', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'announcements', 'list', pos('c1')], { account: undefined });
   });
 
   it('passes all listing flags', async () => {
     await harness.callTool('gog_classroom_announcements_list', { courseId: 'c1', state: 'PUBLISHED', orderBy: 'updateTime desc', max: 20, page: 'tok', all: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['classroom', 'announcements', 'list', 'c1', '--state=PUBLISHED', '--order-by=updateTime desc', '--max=20', '--page=tok', '--all'],
+      ['classroom', 'announcements', 'list', pos('c1'), '--state=PUBLISHED', '--order-by=updateTime desc', '--max=20', '--page=tok', '--all'],
       { account: undefined },
     );
   });
 
   it('omits --all when false', async () => {
     await harness.callTool('gog_classroom_announcements_list', { courseId: 'c1', all: false });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'announcements', 'list', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'announcements', 'list', pos('c1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -350,7 +351,7 @@ describe('gog_classroom_announcements_list', () => {
 describe('gog_classroom_announcements_get', () => {
   it('calls run with ids', async () => {
     await harness.callTool('gog_classroom_announcements_get', { courseId: 'c1', announcementId: 'a1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'announcements', 'get', 'c1', 'a1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'announcements', 'get', pos('c1'), pos('a1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -364,7 +365,7 @@ describe('gog_classroom_announcements_create', () => {
   it('calls run with required text only', async () => {
     await harness.callTool('gog_classroom_announcements_create', { courseId: 'c1', text: 'Hi' });
     expect(runner.run).toHaveBeenCalledWith(
-      ['classroom', 'announcements', 'create', 'c1', '--text=Hi'],
+      ['classroom', 'announcements', 'create', pos('c1'), '--text=Hi'],
       { account: undefined },
     );
   });
@@ -372,7 +373,7 @@ describe('gog_classroom_announcements_create', () => {
   it('passes all optional flags', async () => {
     await harness.callTool('gog_classroom_announcements_create', { courseId: 'c1', text: 'Hi', state: 'DRAFT', scheduled: '2026-05-01T12:00' });
     expect(runner.run).toHaveBeenCalledWith(
-      ['classroom', 'announcements', 'create', 'c1', '--text=Hi', '--state=DRAFT', '--scheduled=2026-05-01T12:00'],
+      ['classroom', 'announcements', 'create', pos('c1'), '--text=Hi', '--state=DRAFT', '--scheduled=2026-05-01T12:00'],
       { account: undefined },
     );
   });
@@ -387,20 +388,20 @@ describe('gog_classroom_announcements_create', () => {
 describe('gog_classroom_topics_list', () => {
   it('calls run with courseId only', async () => {
     await harness.callTool('gog_classroom_topics_list', { courseId: 'c1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'topics', 'list', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'topics', 'list', pos('c1')], { account: undefined });
   });
 
   it('passes all listing flags', async () => {
     await harness.callTool('gog_classroom_topics_list', { courseId: 'c1', max: 20, page: 'tok', all: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['classroom', 'topics', 'list', 'c1', '--max=20', '--page=tok', '--all'],
+      ['classroom', 'topics', 'list', pos('c1'), '--max=20', '--page=tok', '--all'],
       { account: undefined },
     );
   });
 
   it('omits --all when false', async () => {
     await harness.callTool('gog_classroom_topics_list', { courseId: 'c1', all: false });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'topics', 'list', 'c1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'topics', 'list', pos('c1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -413,7 +414,7 @@ describe('gog_classroom_topics_list', () => {
 describe('gog_classroom_topics_get', () => {
   it('calls run with ids', async () => {
     await harness.callTool('gog_classroom_topics_get', { courseId: 'c1', topicId: 't1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'topics', 'get', 'c1', 't1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'topics', 'get', pos('c1'), pos('t1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -452,7 +453,7 @@ describe('gog_classroom_invitations_list', () => {
 describe('gog_classroom_invitations_get', () => {
   it('calls run with invitationId', async () => {
     await harness.callTool('gog_classroom_invitations_get', { invitationId: 'i1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'invitations', 'get', 'i1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'invitations', 'get', pos('i1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -465,7 +466,7 @@ describe('gog_classroom_invitations_get', () => {
 describe('gog_classroom_invitations_accept', () => {
   it('calls run with invitationId', async () => {
     await harness.callTool('gog_classroom_invitations_accept', { invitationId: 'i1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'invitations', 'accept', 'i1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'invitations', 'accept', pos('i1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -483,7 +484,7 @@ describe('gog_classroom_profile_get', () => {
 
   it('passes userId when provided', async () => {
     await harness.callTool('gog_classroom_profile_get', { userId: 'u1' });
-    expect(runner.run).toHaveBeenCalledWith(['classroom', 'profile', 'get', 'u1'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['classroom', 'profile', 'get', pos('u1')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {

package/tests/tools/contacts.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { registerContactsTools } from '../../src/tools/contacts.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_contacts_search', () => {
     vi.mocked(runner.run).mockResolvedValue('{"connections":[]}');
     const harness = await setupHandlers();
     await harness.callTool('gog_contacts_search', { query: 'alice' });
-    expect(runner.run).toHaveBeenCalledWith(['contacts', 'search', 'alice'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['contacts', 'search', pos('alice')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -46,7 +47,7 @@ describe('gog_contacts_get', () => {
     vi.mocked(runner.run).mockResolvedValue('{"resourceName":"people/c123"}');
     const harness = await setupHandlers();
     await harness.callTool('gog_contacts_get', { resourceName: 'people/c123' });
-    expect(runner.run).toHaveBeenCalledWith(['contacts', 'get', 'people/c123'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['contacts', 'get', pos('people/c123')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {

package/tests/tools/docs.test.ts

@@ -1,7 +1,8 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { registerDocsTools } from '../../src/tools/docs.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_docs_info', () => {
     vi.mocked(runner.run).mockResolvedValue('{"title":"My Doc","docId":"abc"}');
     const harness = await setupHandlers();
     const result = await harness.callTool('gog_docs_info', { docId: 'abc' });
-    expect(runner.run).toHaveBeenCalledWith(['docs', 'info', 'abc'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['docs', 'info', pos('abc')], { account: undefined });
     expect(result.content[0].text).toContain('My Doc');
   });
 
@@ -49,7 +50,7 @@ describe('gog_docs_cat', () => {
     vi.mocked(runner.run).mockResolvedValue('Hello world');
     const harness = await setupHandlers();
     const result = await harness.callTool('gog_docs_cat', { docId: 'abc' });
-    expect(runner.run).toHaveBeenCalledWith(['docs', 'cat', 'abc'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['docs', 'cat', pos('abc')], { account: undefined });
     expect(result.content[0].text).toBe('Hello world');
   });
 
@@ -57,14 +58,14 @@ describe('gog_docs_cat', () => {
     vi.mocked(runner.run).mockResolvedValue('text');
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_cat', { docId: 'abc', account: 'other@gmail.com' });
-    expect(runner.run).toHaveBeenCalledWith(['docs', 'cat', 'abc'], { account: 'other@gmail.com' });
+    expect(runner.run).toHaveBeenCalledWith(['docs', 'cat', pos('abc')], { account: 'other@gmail.com' });
   });
 
   it('appends --chips when requested', async () => {
     vi.mocked(runner.run).mockResolvedValue('Hello @person');
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_cat', { docId: 'abc', chips: true });
-    expect(runner.run).toHaveBeenCalledWith(['docs', 'cat', 'abc', '--chips'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['docs', 'cat', pos('abc'), '--chips'], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -80,7 +81,7 @@ describe('gog_docs_create', () => {
     vi.mocked(runner.run).mockResolvedValue('{"docId":"newid","title":"Meeting Notes"}');
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_create', { title: 'Meeting Notes' });
-    expect(runner.run).toHaveBeenCalledWith(['docs', 'create', 'Meeting Notes'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['docs', 'create', pos('Meeting Notes')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -96,7 +97,7 @@ describe('gog_docs_write', () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_write', { docId: 'abc', text: 'Hello world' });
-    expect(runner.run).toHaveBeenCalledWith(['docs', 'write', 'abc', '--text=Hello world'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['docs', 'write', pos('abc'), '--text=Hello world'], { account: undefined });
   });
 
   it('adds --append flag when append is true', async () => {
@@ -104,7 +105,7 @@ describe('gog_docs_write', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_write', { docId: 'abc', text: 'More text', append: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['docs', 'write', 'abc', '--text=More text', '--append'],
+      ['docs', 'write', pos('abc'), '--text=More text', '--append'],
       { account: undefined },
     );
   });
@@ -115,7 +116,7 @@ describe('gog_docs_write', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_write', { docId: 'abc', text: 'T', batch: 'b1' });
     expect(runner.run).toHaveBeenCalledWith(
-      ['docs', 'write', 'abc', '--text=T', '--batch=b1'],
+      ['docs', 'write', pos('abc'), '--text=T', '--batch=b1'],
       { account: undefined },
     );
   });
@@ -126,7 +127,7 @@ describe('gog_docs_write', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_write', { docId: 'abc', text: 'Rewrite', checkOrphans: true });
     expect(runner.run).toHaveBeenCalledWith(
-      ['docs', 'write', 'abc', '--text=Rewrite', '--check-orphans'],
+      ['docs', 'write', pos('abc'), '--text=Rewrite', '--check-orphans'],
       { account: undefined },
     );
   });
@@ -135,7 +136,7 @@ describe('gog_docs_write', () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_write', { docId: 'abc', text: 'text', append: false });
-    expect(runner.run).toHaveBeenCalledWith(['docs', 'write', 'abc', '--text=text'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['docs', 'write', pos('abc'), '--text=text'], { account: undefined });
   });
 
   // gog 0.30.0 paragraph list / indentation / spacing / keep controls
@@ -148,7 +149,7 @@ describe('gog_docs_write', () => {
       keepLinesTogether: true, keepWithNext: true,
     });
     expect(runner.run).toHaveBeenCalledWith(
-      ['docs', 'write', 'abc', '--text=List', '--bullets', '--bullet-preset=BULLET_DISC_CIRCLE_SQUARE',
+      ['docs', 'write', pos('abc'), '--text=List', '--bullets', '--bullet-preset=BULLET_DISC_CIRCLE_SQUARE',
         '--indent-start=18', '--indent-end=6', '--indent-first-line=36', '--space-above=4', '--space-below=8',
         '--keep-lines-together', '--keep-with-next'],
       { account: undefined },
@@ -163,7 +164,7 @@ describe('gog_docs_write', () => {
       keepLinesTogether: false, keepWithNext: false,
     });
     expect(runner.run).toHaveBeenCalledWith(
-      ['docs', 'write', 'abc', '--text=Steps', '--ordered', '--no-bullets',
+      ['docs', 'write', pos('abc'), '--text=Steps', '--ordered', '--no-bullets',
         '--no-keep-lines-together', '--no-keep-with-next'],
       { account: undefined },
     );
@@ -182,7 +183,7 @@ describe('gog_docs_find_replace', () => {
     vi.mocked(runner.run).mockResolvedValue('{"occurrencesChanged":2}');
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_find_replace', { docId: 'abc', find: 'foo', replace: 'bar' });
-    expect(runner.run).toHaveBeenCalledWith(['docs', 'find-replace', 'abc', 'foo', 'bar'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['docs', 'find-replace', pos('abc'), pos('foo'), pos('bar')], { account: undefined });
   });
 
   it('returns error text on failure', async () => {
@@ -198,7 +199,7 @@ describe('gog_docs_structure', () => {
     vi.mocked(runner.run).mockResolvedValue('[1] Heading\n[2] Paragraph');
     const harness = await setupHandlers();
     const result = await harness.callTool('gog_docs_structure', { docId: 'abc' });
-    expect(runner.run).toHaveBeenCalledWith(['docs', 'structure', 'abc'], { account: undefined });
+    expect(runner.run).toHaveBeenCalledWith(['docs', 'structure', pos('abc')], { account: undefined });
     expect(result.content[0].text).toContain('Heading');
   });
 
@@ -210,6 +211,34 @@ describe('gog_docs_structure', () => {
   });
 });
 
+// SEC-3/SEC-4 through the escape hatch: `export --out=~/.zshrc` writes
+// attacker-shaped bytes over a shell profile. GOG_FILE_ROOTS binds it too.
+describe('gog_docs_run path confinement', () => {
+  // The suite runs with GOG_FILE_ROOTS='/'; narrow it so confinement bites.
+  let prevRoots: string | undefined;
+  beforeEach(() => { prevRoots = process.env.GOG_FILE_ROOTS; process.env.GOG_FILE_ROOTS = '/nonexistent-gog-file-root'; });
+  afterEach(() => { process.env.GOG_FILE_ROOTS = prevRoots; });
+
+  it.each([
+    ['export', ['d1', '--out=~/.zshrc']],
+    ['export', ['d1', '--output', '~/.zshrc']],
+    ['insert', ['d1', '--file=/etc/passwd']],
+  ])('refuses docs %s %j', async (subcommand, args) => {
+    const harness = await setupHandlers();
+    const result = await harness.callTool('gog_docs_run', { subcommand, args });
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(/outside the directories/);
+    expect(runner.run).not.toHaveBeenCalled();
+  });
+
+  it('refuses the -f short form, which would hide the path', async () => {
+    const harness = await setupHandlers();
+    const result = await harness.callTool('gog_docs_run', { subcommand: 'insert', args: ['d1', '-f', '/etc/passwd'] });
+    expect(result.isError).toBe(true);
+    expect(runner.run).not.toHaveBeenCalled();
+  });
+});
+
 describe('gog_docs_run', () => {
   it('passes raw subcommand and args to runner', async () => {
     vi.mocked(runner.run).mockResolvedValue('{}');