feat(mcp-server): add permission forecasting and approval bundling to parse_mode

- Define permission class taxonomy (read-only, repo-write, network, destructive, external)
- Create approval bundle grouping for related actions (Ship, Run checks, Install, Review)
- Analyze mode + prompt signals to predict permission needs before execution
- Integrate permissionForecast field into ParseModeResult response
- Add unit tests for forecast generation and integration tests for parse_mode

Closes #1377

Author: JeremyDev87

apps/mcp-server/src/keyword/keyword.service.spec.ts

@@ -2932,4 +2932,35 @@ ${'Even more content.\n'.repeat(150)}`;
       expect(result.requiredSkillsEnforced).toBe(true);
     });
   });
+
+  describe('permissionForecast integration', () => {
+    it('includes permissionForecast in PLAN mode response', async () => {
+      const result = await service.parseMode('PLAN design auth feature');
+      expect(result.permissionForecast).toBeDefined();
+      expect(result.permissionForecast!.permissionClasses).toContain('read-only');
+      expect(result.permissionForecast!.permissionSummary).toContain('PLAN');
+    });
+
+    it('includes permissionForecast in ACT mode response', async () => {
+      const result = await service.parseMode('ACT implement login');
+      expect(result.permissionForecast).toBeDefined();
+      expect(result.permissionForecast!.permissionClasses).toContain('repo-write');
+    });
+
+    it('includes ship bundle when prompt mentions shipping', async () => {
+      const result = await service.parseMode('ACT ship the changes');
+      expect(result.permissionForecast).toBeDefined();
+      const ship = result.permissionForecast!.approvalBundles.find(
+        (b: { name: string }) => b.name === 'Ship changes',
+      );
+      expect(ship).toBeDefined();
+      expect(result.permissionForecast!.permissionClasses).toContain('external');
+    });
+
+    it('provides a human-readable summary', async () => {
+      const result = await service.parseMode('EVAL review PR');
+      expect(typeof result.permissionForecast!.permissionSummary).toBe('string');
+      expect(result.permissionForecast!.permissionSummary.length).toBeGreaterThan(0);
+    });
+  });
 });

apps/mcp-server/src/keyword/keyword.service.ts

@@ -31,6 +31,7 @@ import { filterRulesByMode } from './rule-filter';
 import { truncateSkillContent } from '../skill/skill-content.utils';
 import { createAgentSummary } from '../agent/agent-summary.utils';
 import { truncateRuleContent } from '../rules/rules-content.utils';
+import { generatePermissionForecast } from './permission-forecast';
 import { getDefaultModeConfig } from '../shared/keyword-core';
 import { isTaskmaestroAvailable } from './taskmaestro-detector';
 import { type ClientType } from '../shared/client-type';
@@ -539,6 +540,9 @@ export class KeywordService {
     // 11. Auto-include release checklist in EVAL mode on version changes (#1085)
     this.addReleaseChecklistIfNeeded(result, mode, originalPrompt);
 
+    // 12. Permission forecasting — predict permission needs and bundle related actions (#1377)
+    result.permissionForecast = generatePermissionForecast(mode, originalPrompt);
+
     return result;
   }
 

apps/mcp-server/src/keyword/keyword.types.ts

@@ -7,6 +7,47 @@ export const KEYWORDS = ['PLAN', 'ACT', 'EVAL', 'AUTO'] as const;
 
 export type Mode = (typeof KEYWORDS)[number];
 
+// ─── Permission forecasting types (#1377) ─────────────────────────
+
+/**
+ * Classification of permission levels required for execution actions.
+ * Ordered roughly from least to most impactful.
+ */
+export type PermissionClass =
+  | 'read-only' // file reads, grep, git log
+  | 'repo-write' // file edits, git commit, git push
+  | 'network' // API calls, package install
+  | 'destructive' // file deletion, git reset, branch delete
+  | 'external'; // GitHub API (PR create, issue comment)
+
+/**
+ * A group of related actions that share a logical intent and permission
+ * class.  By surfacing bundles *before* execution, users can anticipate
+ * why approval prompts appear later.
+ */
+export interface ApprovalBundle {
+  /** Short human-readable label, e.g. "Ship changes" */
+  name: string;
+  /** Concrete actions in this bundle */
+  actions: string[];
+  /** Dominant permission class */
+  permissionClass: PermissionClass;
+  /** Why this bundle is needed */
+  reason: string;
+}
+
+/**
+ * Permission forecast attached to a parse_mode response.
+ */
+export interface PermissionForecast {
+  /** Expected permission classes for this mode + task */
+  permissionClasses: PermissionClass[];
+  /** Grouped related actions */
+  approvalBundles: ApprovalBundle[];
+  /** One-line human-readable summary */
+  permissionSummary: string;
+}
+
 /** Mode Agent names in priority order */
 export const MODE_AGENTS = ['plan-mode', 'act-mode', 'eval-mode', 'auto-mode'] as const;
 
@@ -546,6 +587,13 @@ export interface ParseModeResult {
    * Reflects environment, config, or default gating from TeamsCapabilityService (#1311).
    */
   teamsCapability?: TeamsCapabilityStatus;
+  /**
+   * @apiProperty External API - do not rename.
+   * Forecasts the permission classes and approval bundles expected during
+   * execution, so users can anticipate upcoming approval prompts.
+   * Present in all modes.
+   */
+  permissionForecast?: PermissionForecast;
 }
 
 /**

apps/mcp-server/src/keyword/permission-forecast.spec.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from 'vitest';
+import { generatePermissionForecast } from './permission-forecast';
+import type { PermissionClass } from './keyword.types';
+
+describe('generatePermissionForecast', () => {
+  // ── Mode base classes ──────────────────────────────────────────
+
+  describe('mode base permission classes', () => {
+    it('PLAN mode → read-only only', () => {
+      const forecast = generatePermissionForecast('PLAN', 'design auth feature');
+      expect(forecast.permissionClasses).toEqual(['read-only']);
+    });
+
+    it('ACT mode → read-only + repo-write', () => {
+      const forecast = generatePermissionForecast('ACT', 'implement login');
+      expect(forecast.permissionClasses).toContain('read-only');
+      expect(forecast.permissionClasses).toContain('repo-write');
+    });
+
+    it('EVAL mode → read-only only (no prompt signals)', () => {
+      const forecast = generatePermissionForecast('EVAL', 'check code quality');
+      expect(forecast.permissionClasses).toEqual(['read-only']);
+    });
+
+    it('AUTO mode → read-only + repo-write + external', () => {
+      const forecast = generatePermissionForecast('AUTO', 'add login feature');
+      expect(forecast.permissionClasses).toContain('read-only');
+      expect(forecast.permissionClasses).toContain('repo-write');
+      expect(forecast.permissionClasses).toContain('external');
+    });
+  });
+
+  // ── Prompt-signal enrichment ───────────────────────────────────
+
+  describe('prompt-signal enrichment', () => {
+    it('ship-related prompt adds repo-write + external and Ship bundle', () => {
+      const forecast = generatePermissionForecast('ACT', 'ship the changes to GitHub');
+      expect(forecast.permissionClasses).toContain('repo-write');
+      expect(forecast.permissionClasses).toContain('external');
+      const ship = forecast.approvalBundles.find(b => b.name === 'Ship changes');
+      expect(ship).toBeDefined();
+      expect(ship!.actions).toContain('git push');
+      expect(ship!.actions).toContain('gh pr create');
+    });
+
+    it('test-related prompt adds Run checks bundle', () => {
+      const forecast = generatePermissionForecast('ACT', 'run tests and lint');
+      const checks = forecast.approvalBundles.find(b => b.name === 'Run checks');
+      expect(checks).toBeDefined();
+      expect(checks!.actions).toContain('yarn test');
+    });
+
+    it('install-related prompt adds network class and Install bundle', () => {
+      const forecast = generatePermissionForecast('ACT', 'install lodash package');
+      expect(forecast.permissionClasses).toContain('network');
+      const install = forecast.approvalBundles.find(b => b.name === 'Install dependencies');
+      expect(install).toBeDefined();
+    });
+
+    it('delete-related prompt adds destructive class', () => {
+      const forecast = generatePermissionForecast('ACT', 'delete the old migration files');
+      expect(forecast.permissionClasses).toContain('destructive');
+    });
+
+    it('review prompt in EVAL mode adds external class and Review bundle', () => {
+      const forecast = generatePermissionForecast('EVAL', 'review PR 1234');
+      expect(forecast.permissionClasses).toContain('external');
+      const review = forecast.approvalBundles.find(b => b.name === 'Review PR');
+      expect(review).toBeDefined();
+      expect(review!.actions).toContain('gh pr review');
+    });
+
+    it('review prompt in ACT mode does NOT add Review bundle', () => {
+      const forecast = generatePermissionForecast('ACT', 'review the code');
+      const review = forecast.approvalBundles.find(b => b.name === 'Review PR');
+      expect(review).toBeUndefined();
+    });
+  });
+
+  // ── Implicit bundles ───────────────────────────────────────────
+
+  describe('implicit bundles', () => {
+    it('ACT mode with no signal patterns → Code changes bundle', () => {
+      const forecast = generatePermissionForecast('ACT', 'implement user dashboard');
+      const codeChanges = forecast.approvalBundles.find(b => b.name === 'Code changes');
+      expect(codeChanges).toBeDefined();
+      expect(codeChanges!.permissionClass).toBe('repo-write');
+    });
+
+    it('ACT mode with explicit ship signal → no Code changes bundle (has Ship instead)', () => {
+      const forecast = generatePermissionForecast('ACT', 'ship the feature');
+      const codeChanges = forecast.approvalBundles.find(b => b.name === 'Code changes');
+      expect(codeChanges).toBeUndefined();
+    });
+  });
+
+  // ── Permission summary ─────────────────────────────────────────
+
+  describe('permissionSummary', () => {
+    it('is a human-readable string', () => {
+      const forecast = generatePermissionForecast('PLAN', 'design API');
+      expect(typeof forecast.permissionSummary).toBe('string');
+      expect(forecast.permissionSummary.length).toBeGreaterThan(0);
+    });
+
+    it('includes mode name', () => {
+      const forecast = generatePermissionForecast('PLAN', 'design API');
+      expect(forecast.permissionSummary).toContain('PLAN');
+    });
+
+    it('includes highest permission class', () => {
+      const forecast = generatePermissionForecast('ACT', 'ship to GitHub');
+      expect(forecast.permissionSummary).toContain('external');
+    });
+
+    it('includes bundle names when bundles present', () => {
+      const forecast = generatePermissionForecast('ACT', 'ship and run tests');
+      expect(forecast.permissionSummary).toContain('Ship changes');
+      expect(forecast.permissionSummary).toContain('Run checks');
+    });
+
+    it('no bundle names when no bundles', () => {
+      const forecast = generatePermissionForecast('PLAN', 'design API');
+      expect(forecast.permissionSummary).not.toContain('—');
+    });
+  });
+
+  // ── Permission class ordering ──────────────────────────────────
+
+  describe('class ordering', () => {
+    it('returns classes in canonical order: read-only < repo-write < network < destructive < external', () => {
+      const forecast = generatePermissionForecast(
+        'ACT',
+        'delete files, install packages, and ship',
+      );
+      const expected: PermissionClass[] = [
+        'read-only',
+        'repo-write',
+        'network',
+        'destructive',
+        'external',
+      ];
+      expect(forecast.permissionClasses).toEqual(expected);
+    });
+  });
+});