gogcli-mcp-classroom 4.2.5 → 4.4.0

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-classroom",
   "display_name": "gogcli (Classroom)",
-  "version": "4.2.5",
+  "version": "4.4.0",
   "description": "Extended Google Classroom for Claude via gogcli — auth + full Classroom support (courses, rosters, coursework, submissions, announcements, topics, invitations)",
   "author": {
     "name": "Chris Hall",
@@ -39,7 +39,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}"
       }
     }
   },
@@ -55,6 +56,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-classroom",
-  "version": "4.2.5",
+  "version": "4.4.0",
   "mcpName": "io.github.chrischall/gogcli-mcp-classroom",
   "description": "Extended Google Classroom MCP server via gogcli — auth + full Classroom support",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -24,7 +24,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-classroom"
   },
-  "version": "4.2.5",
+  "version": "4.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp-classroom",
-      "version": "4.2.5",
+      "version": "4.4.0",
       "transport": {
         "type": "stdio"
       },

package/src/tools/classroom-extra.ts

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from '../../../gogcli-mcp/src/lib.js';
+import { accountParam, runOrDiagnose, pos, readCourse, requireDispatchConfirmation, CONFIRM_FALLBACK_DESCRIPTION, confirmTokenParam } from '../../../gogcli-mcp/src/lib.js';
+import type { GogArg } from '../../../gogcli-mcp/src/lib.js';
 
 const courseState = z.enum(['ACTIVE', 'ARCHIVED', 'PROVISIONED', 'DECLINED', 'SUSPENDED']);
 const workState = z.enum(['PUBLISHED', 'DRAFT']);
@@ -41,7 +42,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ name, owner, section, descriptionHeading, description, room, state, account }) => {
-    const args = ['classroom', 'courses', 'create', `--name=${name}`];
+    const args: GogArg[] = ['classroom', 'courses', 'create', `--name=${name}`];
     if (owner) args.push(`--owner=${owner}`);
     if (section) args.push(`--section=${section}`);
     if (descriptionHeading) args.push(`--description-heading=${descriptionHeading}`);
@@ -61,7 +62,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, name, owner, section, descriptionHeading, description, room, state, account }) => {
-    const args = ['classroom', 'courses', 'update', courseId];
+    const args: GogArg[] = ['classroom', 'courses', 'update', pos(courseId)];
     if (name) args.push(`--name=${name}`);
     if (owner) args.push(`--owner=${owner}`);
     if (section) args.push(`--section=${section}`);
@@ -80,7 +81,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, account }) => {
-    return runOrDiagnose(['classroom', 'courses', 'delete', courseId, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
+    return runOrDiagnose(['classroom', 'courses', 'delete', pos(courseId), '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_classroom_courses_archive', {
@@ -91,7 +92,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, account }) => {
-    return runOrDiagnose(['classroom', 'courses', 'archive', courseId], { account });
+    return runOrDiagnose(['classroom', 'courses', 'archive', pos(courseId)], { account });
   });
 
   server.registerTool('gog_classroom_courses_unarchive', {
@@ -102,7 +103,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, account }) => {
-    return runOrDiagnose(['classroom', 'courses', 'unarchive', courseId], { account });
+    return runOrDiagnose(['classroom', 'courses', 'unarchive', pos(courseId)], { account });
   });
 
   server.registerTool('gog_classroom_students_add', {
@@ -115,7 +116,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, userId, enrollmentCode, account }) => {
-    const args = ['classroom', 'students', 'add', courseId, userId];
+    const args: GogArg[] = ['classroom', 'students', 'add', pos(courseId), pos(userId)];
     if (enrollmentCode) args.push(`--enrollment-code=${enrollmentCode}`);
     return runOrDiagnose(args, { account });
   });
@@ -129,7 +130,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, userId, account }) => {
-    return runOrDiagnose(['classroom', 'students', 'remove', courseId, userId, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
+    return runOrDiagnose(['classroom', 'students', 'remove', pos(courseId), pos(userId), '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_classroom_teachers_add', {
@@ -141,7 +142,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, userId, account }) => {
-    return runOrDiagnose(['classroom', 'teachers', 'add', courseId, userId], { account });
+    return runOrDiagnose(['classroom', 'teachers', 'add', pos(courseId), pos(userId)], { account });
   });
 
   server.registerTool('gog_classroom_teachers_remove', {
@@ -153,7 +154,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, userId, account }) => {
-    return runOrDiagnose(['classroom', 'teachers', 'remove', courseId, userId, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
+    return runOrDiagnose(['classroom', 'teachers', 'remove', pos(courseId), pos(userId), '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_classroom_coursework_create', {
@@ -166,7 +167,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, title, description, type, state, maxPoints, due, dueDate, dueTime, scheduled, topic, account }) => {
-    const args = ['classroom', 'coursework', 'create', courseId, `--title=${title}`];
+    const args: GogArg[] = ['classroom', 'coursework', 'create', pos(courseId), `--title=${title}`];
     if (description) args.push(`--description=${description}`);
     if (type) args.push(`--type=${type}`);
     if (state) args.push(`--state=${state}`);
@@ -190,7 +191,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, courseworkId, title, description, type, state, maxPoints, due, dueDate, dueTime, scheduled, topic, account }) => {
-    const args = ['classroom', 'coursework', 'update', courseId, courseworkId];
+    const args: GogArg[] = ['classroom', 'coursework', 'update', pos(courseId), pos(courseworkId)];
     if (title) args.push(`--title=${title}`);
     if (description) args.push(`--description=${description}`);
     if (type) args.push(`--type=${type}`);
@@ -213,7 +214,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, courseworkId, account }) => {
-    return runOrDiagnose(['classroom', 'coursework', 'delete', courseId, courseworkId, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
+    return runOrDiagnose(['classroom', 'coursework', 'delete', pos(courseId), pos(courseworkId), '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_classroom_announcements_update', {
@@ -228,7 +229,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, announcementId, text, state, scheduled, account }) => {
-    const args = ['classroom', 'announcements', 'update', courseId, announcementId];
+    const args: GogArg[] = ['classroom', 'announcements', 'update', pos(courseId), pos(announcementId)];
     if (text) args.push(`--text=${text}`);
     if (state) args.push(`--state=${state}`);
     if (scheduled) args.push(`--scheduled=${scheduled}`);
@@ -244,7 +245,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, announcementId, account }) => {
-    return runOrDiagnose(['classroom', 'announcements', 'delete', courseId, announcementId, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
+    return runOrDiagnose(['classroom', 'announcements', 'delete', pos(courseId), pos(announcementId), '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_classroom_topics_create', {
@@ -256,7 +257,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, name, account }) => {
-    return runOrDiagnose(['classroom', 'topics', 'create', courseId, `--name=${name}`], { account });
+    return runOrDiagnose(['classroom', 'topics', 'create', pos(courseId), `--name=${name}`], { account });
   });
 
   server.registerTool('gog_classroom_topics_update', {
@@ -269,7 +270,7 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, topicId, name, account }) => {
-    return runOrDiagnose(['classroom', 'topics', 'update', courseId, topicId, `--name=${name}`], { account });
+    return runOrDiagnose(['classroom', 'topics', 'update', pos(courseId), pos(topicId), `--name=${name}`], { account });
   });
 
   server.registerTool('gog_classroom_topics_delete', {
@@ -281,20 +282,42 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ courseId, topicId, account }) => {
-    return runOrDiagnose(['classroom', 'topics', 'delete', courseId, topicId, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
+    return runOrDiagnose(['classroom', 'topics', 'delete', pos(courseId), pos(topicId), '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_classroom_invitations_create', {
-    description: 'Create an invitation to a Google Classroom course.',
+    description: 'Create an invitation to a Google Classroom course — Classroom emails the invitee. Reads the course '
+      + 'and asks the MCP host to show the user a confirmation prompt with the class, the invitee and the role; '
+      + 'nothing is sent unless they accept.' + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       courseId: z.string().describe('Course ID'),
       userId: z.string().describe('User ID to invite'),
       role: z.enum(['STUDENT', 'TEACHER', 'OWNER']).describe('Role for the invited user'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ courseId, userId, role, account }) => {
-    return runOrDiagnose(['classroom', 'invitations', 'create', courseId, userId, `--role=${role}`], { account });
+  }, async ({ courseId, userId, role, account, confirmToken }, ctx) => {
+    const read = await readCourse(courseId, account, runOrDiagnose);
+    if (read.error) return read.error;
+    const invitation = { course: read.course, invitee: userId, role };
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: 'classroom.invitation-create',
+      message: role === 'OWNER'
+        ? 'Review and confirm this Classroom invitation — it offers OWNERSHIP of the course:'
+        : 'Review and confirm this Classroom invitation:',
+      confirmationLabel: 'Confirm that this invitation should be sent now.',
+      details: invitation,
+      unsupportedNote: 'Ask the user to invite them from Classroom.',
+      fallback: {
+        tool: 'gog_classroom_invitations_create',
+        account,
+        confirmToken,
+        subject: () => ({ target: `${courseId}/${userId}`, payload: invitation, preview: invitation }),
+      },
+    });
+    if (confirmation) return confirmation;
+    return runOrDiagnose(['classroom', 'invitations', 'create', pos(courseId), pos(userId), `--role=${role}`], { account });
   });
 
   server.registerTool('gog_classroom_invitations_delete', {
@@ -305,6 +328,6 @@ export function registerExtraClassroomTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ invitationId, account }) => {
-    return runOrDiagnose(['classroom', 'invitations', 'delete', invitationId, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
+    return runOrDiagnose(['classroom', 'invitations', 'delete', pos(invitationId), '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 }

package/tests/tools/classroom-extra.test.ts

@@ -3,6 +3,7 @@ import { registerExtraClassroomTools } from '../../src/tools/classroom-extra.js'
 import * as lib from '../../../gogcli-mcp/src/lib.js';
 import { createTestHarness, type TestHarness } from '@chrischall/mcp-utils/test';
 import { rawTextResult } from '@chrischall/mcp-utils';
+import { pos } from '../../../gogcli-mcp/src/argv.js';
 
 vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
   const actual = await importOriginal<typeof lib>();
@@ -17,7 +18,9 @@ let harness: TestHarness;
 beforeEach(async () => {
   vi.clearAllMocks();
   vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
-  harness = await createTestHarness(registerExtraClassroomTools);
+  harness = await createTestHarness(registerExtraClassroomTools, {
+    elicitation: async () => ({ action: 'accept', content: { confirmed: true } }),
+  });
 });
 
 describe('gog_classroom_courses_create', () => {
@@ -49,7 +52,7 @@ describe('gog_classroom_courses_create', () => {
 describe('gog_classroom_courses_update', () => {
   it('calls runOrDiagnose with courseId only', async () => {
     await harness.callTool('gog_classroom_courses_update', { courseId: 'c1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'courses', 'update', 'c1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'courses', 'update', pos('c1')], { account: undefined });
   });
 
   it('passes all optional flags', async () => {
@@ -64,7 +67,7 @@ describe('gog_classroom_courses_update', () => {
       state: 'ARCHIVED',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['classroom', 'courses', 'update', 'c1', '--name=New Name', '--owner=me', '--section=B', '--description-heading=Heading', '--description=Desc', '--room=R2', '--state=ARCHIVED'],
+      ['classroom', 'courses', 'update', pos('c1'), '--name=New Name', '--owner=me', '--section=B', '--description-heading=Heading', '--description=Desc', '--room=R2', '--state=ARCHIVED'],
       { account: undefined },
     );
   });
@@ -73,34 +76,34 @@ describe('gog_classroom_courses_update', () => {
 describe('gog_classroom_courses_delete', () => {
   it('calls runOrDiagnose with courseId', async () => {
     await harness.callTool('gog_classroom_courses_delete', { courseId: 'c1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'courses', 'delete', 'c1', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'courses', 'delete', pos('c1'), '--force'], { account: undefined });
   });
 });
 
 describe('gog_classroom_courses_archive', () => {
   it('calls runOrDiagnose with courseId', async () => {
     await harness.callTool('gog_classroom_courses_archive', { courseId: 'c1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'courses', 'archive', 'c1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'courses', 'archive', pos('c1')], { account: undefined });
   });
 });
 
 describe('gog_classroom_courses_unarchive', () => {
   it('calls runOrDiagnose with courseId', async () => {
     await harness.callTool('gog_classroom_courses_unarchive', { courseId: 'c1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'courses', 'unarchive', 'c1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'courses', 'unarchive', pos('c1')], { account: undefined });
   });
 });
 
 describe('gog_classroom_students_add', () => {
   it('calls runOrDiagnose with courseId and userId', async () => {
     await harness.callTool('gog_classroom_students_add', { courseId: 'c1', userId: 'u1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'students', 'add', 'c1', 'u1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'students', 'add', pos('c1'), pos('u1')], { account: undefined });
   });
 
   it('passes --enrollment-code when provided', async () => {
     await harness.callTool('gog_classroom_students_add', { courseId: 'c1', userId: 'u1', enrollmentCode: 'abc123' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['classroom', 'students', 'add', 'c1', 'u1', '--enrollment-code=abc123'],
+      ['classroom', 'students', 'add', pos('c1'), pos('u1'), '--enrollment-code=abc123'],
       { account: undefined },
     );
   });
@@ -109,21 +112,21 @@ describe('gog_classroom_students_add', () => {
 describe('gog_classroom_students_remove', () => {
   it('calls runOrDiagnose with courseId and userId', async () => {
     await harness.callTool('gog_classroom_students_remove', { courseId: 'c1', userId: 'u1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'students', 'remove', 'c1', 'u1', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'students', 'remove', pos('c1'), pos('u1'), '--force'], { account: undefined });
   });
 });
 
 describe('gog_classroom_teachers_add', () => {
   it('calls runOrDiagnose with courseId and userId', async () => {
     await harness.callTool('gog_classroom_teachers_add', { courseId: 'c1', userId: 'u1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'teachers', 'add', 'c1', 'u1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'teachers', 'add', pos('c1'), pos('u1')], { account: undefined });
   });
 });
 
 describe('gog_classroom_teachers_remove', () => {
   it('calls runOrDiagnose with courseId and userId', async () => {
     await harness.callTool('gog_classroom_teachers_remove', { courseId: 'c1', userId: 'u1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'teachers', 'remove', 'c1', 'u1', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'teachers', 'remove', pos('c1'), pos('u1'), '--force'], { account: undefined });
   });
 });
 
@@ -131,7 +134,7 @@ describe('gog_classroom_coursework_create', () => {
   it('calls runOrDiagnose with required title only', async () => {
     await harness.callTool('gog_classroom_coursework_create', { courseId: 'c1', title: 'HW1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['classroom', 'coursework', 'create', 'c1', '--title=HW1'],
+      ['classroom', 'coursework', 'create', pos('c1'), '--title=HW1'],
       { account: undefined },
     );
   });
@@ -151,7 +154,7 @@ describe('gog_classroom_coursework_create', () => {
       topic: 't1',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['classroom', 'coursework', 'create', 'c1', '--title=HW1', '--description=Chapter 1', '--type=ASSIGNMENT', '--state=PUBLISHED', '--max-points=100', '--due=2026-05-01T23:59', '--due-date=2026-05-01', '--due-time=23:59', '--scheduled=2026-04-30T12:00', '--topic=t1'],
+      ['classroom', 'coursework', 'create', pos('c1'), '--title=HW1', '--description=Chapter 1', '--type=ASSIGNMENT', '--state=PUBLISHED', '--max-points=100', '--due=2026-05-01T23:59', '--due-date=2026-05-01', '--due-time=23:59', '--scheduled=2026-04-30T12:00', '--topic=t1'],
       { account: undefined },
     );
   });
@@ -160,7 +163,7 @@ describe('gog_classroom_coursework_create', () => {
 describe('gog_classroom_coursework_update', () => {
   it('calls runOrDiagnose with ids only', async () => {
     await harness.callTool('gog_classroom_coursework_update', { courseId: 'c1', courseworkId: 'w1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'coursework', 'update', 'c1', 'w1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'coursework', 'update', pos('c1'), pos('w1')], { account: undefined });
   });
 
   it('passes all optional flags', async () => {
@@ -179,7 +182,7 @@ describe('gog_classroom_coursework_update', () => {
       topic: 't1',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['classroom', 'coursework', 'update', 'c1', 'w1', '--title=New Title', '--description=Desc', '--type=SHORT_ANSWER_QUESTION', '--state=DRAFT', '--max-points=50', '--due=2026-05-01T23:59', '--due-date=2026-05-01', '--due-time=23:59', '--scheduled=2026-04-30T12:00', '--topic=t1'],
+      ['classroom', 'coursework', 'update', pos('c1'), pos('w1'), '--title=New Title', '--description=Desc', '--type=SHORT_ANSWER_QUESTION', '--state=DRAFT', '--max-points=50', '--due=2026-05-01T23:59', '--due-date=2026-05-01', '--due-time=23:59', '--scheduled=2026-04-30T12:00', '--topic=t1'],
       { account: undefined },
     );
   });
@@ -188,14 +191,14 @@ describe('gog_classroom_coursework_update', () => {
 describe('gog_classroom_coursework_delete', () => {
   it('calls runOrDiagnose with ids', async () => {
     await harness.callTool('gog_classroom_coursework_delete', { courseId: 'c1', courseworkId: 'w1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'coursework', 'delete', 'c1', 'w1', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'coursework', 'delete', pos('c1'), pos('w1'), '--force'], { account: undefined });
   });
 });
 
 describe('gog_classroom_announcements_update', () => {
   it('calls runOrDiagnose with ids only', async () => {
     await harness.callTool('gog_classroom_announcements_update', { courseId: 'c1', announcementId: 'a1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'announcements', 'update', 'c1', 'a1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'announcements', 'update', pos('c1'), pos('a1')], { account: undefined });
   });
 
   it('passes all optional flags', async () => {
@@ -207,7 +210,7 @@ describe('gog_classroom_announcements_update', () => {
       scheduled: '2026-05-01T12:00',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['classroom', 'announcements', 'update', 'c1', 'a1', '--text=edited', '--state=PUBLISHED', '--scheduled=2026-05-01T12:00'],
+      ['classroom', 'announcements', 'update', pos('c1'), pos('a1'), '--text=edited', '--state=PUBLISHED', '--scheduled=2026-05-01T12:00'],
       { account: undefined },
     );
   });
@@ -216,7 +219,7 @@ describe('gog_classroom_announcements_update', () => {
 describe('gog_classroom_announcements_delete', () => {
   it('calls runOrDiagnose with ids', async () => {
     await harness.callTool('gog_classroom_announcements_delete', { courseId: 'c1', announcementId: 'a1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'announcements', 'delete', 'c1', 'a1', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'announcements', 'delete', pos('c1'), pos('a1'), '--force'], { account: undefined });
   });
 });
 
@@ -224,7 +227,7 @@ describe('gog_classroom_topics_create', () => {
   it('calls runOrDiagnose with courseId and name', async () => {
     await harness.callTool('gog_classroom_topics_create', { courseId: 'c1', name: 'Week 1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['classroom', 'topics', 'create', 'c1', '--name=Week 1'],
+      ['classroom', 'topics', 'create', pos('c1'), '--name=Week 1'],
       { account: undefined },
     );
   });
@@ -234,7 +237,7 @@ describe('gog_classroom_topics_update', () => {
   it('calls runOrDiagnose with ids and name', async () => {
     await harness.callTool('gog_classroom_topics_update', { courseId: 'c1', topicId: 't1', name: 'Week 2' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['classroom', 'topics', 'update', 'c1', 't1', '--name=Week 2'],
+      ['classroom', 'topics', 'update', pos('c1'), pos('t1'), '--name=Week 2'],
       { account: undefined },
     );
   });
@@ -243,15 +246,64 @@ describe('gog_classroom_topics_update', () => {
 describe('gog_classroom_topics_delete', () => {
   it('calls runOrDiagnose with ids', async () => {
     await harness.callTool('gog_classroom_topics_delete', { courseId: 'c1', topicId: 't1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'topics', 'delete', 'c1', 't1', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'topics', 'delete', pos('c1'), pos('t1'), '--force'], { account: undefined });
   });
 });
 
 describe('gog_classroom_invitations_create', () => {
+  const COURSE = rawTextResult(JSON.stringify({ course: { id: 'c1', name: 'Algebra II' } }));
+
+  it('reads the course and prompts with the class, invitee and role', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(COURSE);
+    let message = '';
+    const h = await createTestHarness(registerExtraClassroomTools, {
+      elicitation: async (r) => { message = r.params.message; return { action: 'decline' }; },
+    });
+    await h.callTool('gog_classroom_invitations_create', { courseId: 'c1', userId: 'kid@example.com', role: 'OWNER' });
+    expect(message).toMatch(/OWNERSHIP/);
+    expect(JSON.parse(message.split('\n').slice(1).join('\n')).details)
+      .toEqual({ course: { id: 'c1', name: 'Algebra II' }, invitee: 'kid@example.com', role: 'OWNER' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'courses', 'get', pos('c1')], { account: undefined });
+    expect(lib.runOrDiagnose).not.toHaveBeenCalledWith(
+      ['classroom', 'invitations', 'create', pos('c1'), pos('kid@example.com'), '--role=OWNER'], { account: undefined });
+  });
+
+  it('refuses a client that cannot be prompted', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(COURSE);
+    const h = await createTestHarness(registerExtraClassroomTools);
+    const r = JSON.parse((await h.callTool('gog_classroom_invitations_create', { courseId: 'c1', userId: 'u1', role: 'STUDENT' })).content[0]!.text as string);
+    expect(r).toMatchObject({ reason: 'confirmation-unsupported', action: 'classroom.invitation-create' });
+    expect(r.note).toMatch(/invite them from Classroom/);
+  });
+
+  it('token fallback: phase 1 previews, phase 2 invites', async () => {
+    const ORIGINAL = { ...process.env };
+    process.env.GOG_SEND_CONFIRM_FALLBACK = 'token';
+    try {
+      vi.mocked(lib.runOrDiagnose).mockResolvedValue(COURSE);
+      const h = await createTestHarness(registerExtraClassroomTools);
+      const args = { courseId: 'c1', userId: 'u1', role: 'STUDENT' as const };
+      const p1 = JSON.parse((await h.callTool('gog_classroom_invitations_create', args)).content[0]!.text as string);
+      expect(p1.preview).toEqual({ course: { id: 'c1', name: 'Algebra II' }, invitee: 'u1', role: 'STUDENT' });
+      await h.callTool('gog_classroom_invitations_create', { ...args, confirmToken: p1.confirmToken });
+      expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+        ['classroom', 'invitations', 'create', pos('c1'), pos('u1'), '--role=STUDENT'], { account: undefined });
+    } finally {
+      process.env = ORIGINAL;
+    }
+  });
+
+  it('returns a failed course read without inviting', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue({ content: [{ type: 'text', text: 'Error: not found' }], isError: true });
+    const r = await harness.callTool('gog_classroom_invitations_create', { courseId: 'c1', userId: 'u1', role: 'STUDENT' });
+    expect(r.isError).toBe(true);
+    expect(lib.runOrDiagnose).toHaveBeenCalledTimes(1);
+  });
+
   it('calls runOrDiagnose with courseId, userId, role', async () => {
     await harness.callTool('gog_classroom_invitations_create', { courseId: 'c1', userId: 'u1', role: 'STUDENT' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['classroom', 'invitations', 'create', 'c1', 'u1', '--role=STUDENT'],
+      ['classroom', 'invitations', 'create', pos('c1'), pos('u1'), '--role=STUDENT'],
       { account: undefined },
     );
   });
@@ -260,6 +312,6 @@ describe('gog_classroom_invitations_create', () => {
 describe('gog_classroom_invitations_delete', () => {
   it('calls runOrDiagnose with invitationId', async () => {
     await harness.callTool('gog_classroom_invitations_delete', { invitationId: 'i1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'invitations', 'delete', 'i1', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['classroom', 'invitations', 'delete', pos('i1'), '--force'], { account: undefined });
   });
 });

package/vitest.config.ts

@@ -2,6 +2,11 @@ import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
   test: {
+    // The arg-shape tests pass arbitrary server paths; confinement is exercised
+    // explicitly by the tests that narrow GOG_FILE_ROOTS themselves.
+    env: {
+      GOG_FILE_ROOTS: '/',
+    },
     coverage: {
       provider: 'v8',
       include: ['src/**/*.ts'],