feat(mcp): expose nested execution metadata in parse_mode (#1312)

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

@@ -1,4 +1,15 @@
-import type { Mode } from '../keyword/keyword.types';
+// Mode is defined in keyword.types but importing it directly creates a circular dependency
+// (agent.types → keyword.types → execution-plan.types ← agent.types via re-export).
+// Local alias breaks the cycle while preserving type safety.
+type Mode = 'PLAN' | 'ACT' | 'EVAL' | 'AUTO';
+
+import type {
+  DispatchedAgent,
+  TaskmaestroDispatch,
+  TeamsDispatch,
+  VisibilityConfig,
+  ExecutionPlan,
+} from './execution-plan.types';
 
 /**
  * Agent Stack - a pre-configured team of agents for common workflows
@@ -69,156 +80,23 @@ export interface ParallelAgentSet {
   failedAgents?: FailedAgent[];
 }
 
-/**
- * Dispatch parameters for a single agent, ready to use with Claude Code Task tool
- */
-export interface DispatchParams {
-  subagent_type: 'general-purpose';
-  prompt: string;
-  description: string;
-  run_in_background?: true;
-}
-
-/**
- * A dispatched agent with metadata and Task-tool-ready parameters
- */
-export interface DispatchedAgent {
-  name: string;
-  displayName: string;
-  description: string;
-  dispatchParams: DispatchParams;
-}
-
-/**
- * Inner Teams coordination metadata embedded in a TaskMaestro pane assignment.
- * Present only when the composable `taskmaestro+teams` strategy is active
- * and the Teams capability gate is enabled.
- */
-export interface InnerTeamsSpec {
-  type: 'teams';
-  teamSpec: {
-    team_name: string;
-    description: string;
-  };
-  teammates: Array<{
-    name: string;
-    subagent_type: 'general-purpose';
-  }>;
-}
-
-/**
- * A single TaskMaestro pane assignment with agent name and prompt.
- * When the composable `taskmaestro+teams` strategy is active,
- * `innerCoordination` carries the metadata a pane worker needs
- * to bootstrap its inner Teams workflow.
- */
-export interface TaskmaestroAssignment {
-  name: string;
-  displayName: string;
-  prompt: string;
-  /** Inner coordination metadata for composable taskmaestro+teams execution */
-  innerCoordination?: InnerTeamsSpec;
-}
-
-/**
- * TaskMaestro dispatch configuration for parallel tmux pane execution
- */
-export interface TaskmaestroDispatch {
-  sessionName: string;
-  paneCount: number;
-  assignments: TaskmaestroAssignment[];
-}
-
-/**
- * A single teammate in a Teams dispatch configuration
- */
-export interface TeamsTeammate {
-  name: string;
-  subagent_type: 'general-purpose';
-  team_name: string;
-  prompt: string;
-}
-
-/**
- * Teams dispatch configuration for Claude Code native team coordination
- */
-export interface TeamsDispatch {
-  team_name: string;
-  description: string;
-  teammates: TeamsTeammate[];
-}
-
-/**
- * SendMessage-based progress reporting instructions for specialist visibility
- */
-export interface VisibilityMessages {
-  onStart: string;
-  onFinding: string;
-  onComplete: string;
-}
-
-/**
- * Configuration for real-time specialist execution visibility via Teams messaging
- */
-export interface VisibilityConfig {
-  reportTo: string;
-  format: string;
-  includeProgress: boolean;
-  messages?: VisibilityMessages;
-}
-
-/**
- * Execution layer: subagent strategy
- */
-export interface SubagentLayer {
-  type: 'subagent';
-  agents: DispatchedAgent[];
-}
-
-/**
- * Execution layer: TaskMaestro tmux-based transport
- */
-export interface TaskmaestroLayer {
-  type: 'taskmaestro';
-  config: TaskmaestroDispatch;
-}
-
-/**
- * Execution layer: Claude Code native Teams coordination
- */
-export interface TeamsLayer {
-  type: 'teams';
-  config: TeamsDispatch;
-  visibility?: VisibilityConfig;
-}
-
-/**
- * Discriminated union of all execution layer types.
- * Each layer represents a single execution strategy.
- */
-export type ExecutionLayer = SubagentLayer | TaskmaestroLayer | TeamsLayer;
-
-/**
- * Composable execution plan with outer transport and optional inner coordination.
- *
- * Simple plan:  outerExecution only (e.g. subagent, taskmaestro, or teams)
- * Nested plan:  outerExecution + innerCoordination (e.g. taskmaestro + teams)
- *
- * @example
- * // Simple subagent plan
- * { outerExecution: { type: 'subagent', agents: [...] } }
- *
- * @example
- * // Nested: TaskMaestro as transport, Teams as coordination
- * {
- *   outerExecution: { type: 'taskmaestro', config: {...} },
- *   innerCoordination: { type: 'teams', config: {...} }
- * }
- */
-export interface ExecutionPlan {
-  outerExecution: ExecutionLayer;
-  innerCoordination?: ExecutionLayer;
-}
+// Re-export execution plan types from dedicated file (avoids circular dep with keyword.types)
+export type {
+  DispatchParams,
+  DispatchedAgent,
+  InnerTeamsSpec,
+  TaskmaestroAssignment,
+  TaskmaestroDispatch,
+  TeamsTeammate,
+  TeamsDispatch,
+  VisibilityMessages,
+  VisibilityConfig,
+  SubagentLayer,
+  TaskmaestroLayer,
+  TeamsLayer,
+  ExecutionLayer,
+  ExecutionPlan,
+} from './execution-plan.types';
 
 /**
  * Result of dispatching agents for execution

apps/mcp-server/src/agent/execution-plan.ts

@@ -5,7 +5,7 @@ import type {
   TaskmaestroDispatch,
   TeamsDispatch,
   VisibilityConfig,
-} from './agent.types';
+} from './execution-plan.types';
 
 /**
  * Build a single-layer execution plan.

apps/mcp-server/src/agent/execution-plan.types.ts

@@ -0,0 +1,158 @@
+/**
+ * Execution plan types extracted from agent.types.ts to break the
+ * circular dependency: agent.types → keyword.types → agent.types.
+ *
+ * These types are consumed by keyword.types.ts (ParseModeResult) and
+ * re-exported from agent.types.ts for backward compatibility.
+ */
+
+/**
+ * Dispatch parameters for a single agent, ready to use with Claude Code Task tool
+ */
+export interface DispatchParams {
+  subagent_type: 'general-purpose';
+  prompt: string;
+  description: string;
+  run_in_background?: true;
+}
+
+/**
+ * A dispatched agent with metadata and Task-tool-ready parameters
+ */
+export interface DispatchedAgent {
+  name: string;
+  displayName: string;
+  description: string;
+  dispatchParams: DispatchParams;
+}
+
+/**
+ * Inner Teams coordination metadata embedded in a TaskMaestro pane assignment.
+ * Present only when the composable `taskmaestro+teams` strategy is active
+ * and the Teams capability gate is enabled.
+ */
+export interface InnerTeamsSpec {
+  type: 'teams';
+  teamSpec: {
+    team_name: string;
+    description: string;
+  };
+  teammates: Array<{
+    name: string;
+    subagent_type: 'general-purpose';
+  }>;
+}
+
+/**
+ * A single TaskMaestro pane assignment with agent name and prompt.
+ * When the composable `taskmaestro+teams` strategy is active,
+ * `innerCoordination` carries the metadata a pane worker needs
+ * to bootstrap its inner Teams workflow.
+ */
+export interface TaskmaestroAssignment {
+  name: string;
+  displayName: string;
+  prompt: string;
+  /** Inner coordination metadata for composable taskmaestro+teams execution */
+  innerCoordination?: InnerTeamsSpec;
+}
+
+/**
+ * TaskMaestro dispatch configuration for parallel tmux pane execution
+ */
+export interface TaskmaestroDispatch {
+  sessionName: string;
+  paneCount: number;
+  assignments: TaskmaestroAssignment[];
+}
+
+/**
+ * A single teammate in a Teams dispatch configuration
+ */
+export interface TeamsTeammate {
+  name: string;
+  subagent_type: 'general-purpose';
+  team_name: string;
+  prompt: string;
+}
+
+/**
+ * Teams dispatch configuration for Claude Code native team coordination
+ */
+export interface TeamsDispatch {
+  team_name: string;
+  description: string;
+  teammates: TeamsTeammate[];
+}
+
+/**
+ * SendMessage-based progress reporting instructions for specialist visibility
+ */
+export interface VisibilityMessages {
+  onStart: string;
+  onFinding: string;
+  onComplete: string;
+}
+
+/**
+ * Configuration for real-time specialist execution visibility via Teams messaging
+ */
+export interface VisibilityConfig {
+  reportTo: string;
+  format: string;
+  includeProgress: boolean;
+  messages?: VisibilityMessages;
+}
+
+/**
+ * Execution layer: subagent strategy
+ */
+export interface SubagentLayer {
+  type: 'subagent';
+  agents: DispatchedAgent[];
+}
+
+/**
+ * Execution layer: TaskMaestro tmux-based transport
+ */
+export interface TaskmaestroLayer {
+  type: 'taskmaestro';
+  config: TaskmaestroDispatch;
+}
+
+/**
+ * Execution layer: Claude Code native Teams coordination
+ */
+export interface TeamsLayer {
+  type: 'teams';
+  config: TeamsDispatch;
+  visibility?: VisibilityConfig;
+}
+
+/**
+ * Discriminated union of all execution layer types.
+ * Each layer represents a single execution strategy.
+ */
+export type ExecutionLayer = SubagentLayer | TaskmaestroLayer | TeamsLayer;
+
+/**
+ * Composable execution plan with outer transport and optional inner coordination.
+ *
+ * Simple plan:  outerExecution only (e.g. subagent, taskmaestro, or teams)
+ * Nested plan:  outerExecution + innerCoordination (e.g. taskmaestro + teams)
+ *
+ * @example
+ * // Simple subagent plan
+ * { outerExecution: { type: 'subagent', agents: [...] } }
+ *
+ * @example
+ * // Nested: TaskMaestro as transport, Teams as coordination
+ * {
+ *   outerExecution: { type: 'taskmaestro', config: {...} },
+ *   innerCoordination: { type: 'teams', config: {...} }
+ * }
+ */
+export interface ExecutionPlan {
+  outerExecution: ExecutionLayer;
+  innerCoordination?: ExecutionLayer;
+}

apps/mcp-server/src/agent/index.ts

@@ -9,3 +9,4 @@ export * from './agent-prompt.builder';
 export * from './agent-stack.schema';
 export * from './agent-stack.loader';
 export * from './execution-plan';
+export * from './execution-plan.types';

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

@@ -1,6 +1,8 @@
 import type { DiffAnalysisResult } from './diff-analyzer';
 import type { CouncilPreset } from '../agent/council-preset.types';
 import type { CouncilSummary } from '../collaboration/council-summary.types';
+import type { ExecutionPlan } from '../agent/execution-plan.types';
+import type { TeamsCapabilityStatus } from '../agent/teams-capability.types';
 
 export const KEYWORDS = ['PLAN', 'ACT', 'EVAL', 'AUTO'] as const;
 
@@ -523,6 +525,18 @@ export interface ParseModeResult {
    * Clients should treat this as read-only diagnostic data.
    */
   councilSummary?: CouncilSummary;
+  /**
+   * @apiProperty External API - do not rename.
+   * Describes the outer execution transport and optional inner coordination layer.
+   * Built from the composable execution model (#1309). Present when dispatch is active.
+   */
+  executionPlan?: ExecutionPlan;
+  /**
+   * @apiProperty External API - do not rename.
+   * Runtime capability status for Teams coordination.
+   * Reflects environment, config, or default gating from TeamsCapabilityService (#1311).
+   */
+  teamsCapability?: TeamsCapabilityStatus;
 }
 
 /**