feat: implement Agent Identity & Self-Awareness System

packages/types/src/global-settings.ts

@@ -13,6 +13,7 @@ import { experimentsSchema } from "./experiment.js"
 import { telemetrySettingsSchema } from "./telemetry.js"
 import { modeConfigSchema } from "./mode.js"
 import { customModePromptsSchema, customSupportPromptsSchema } from "./mode.js"
+import { personalitySchema } from "./personality.js"
 import { languagesSchema } from "./vscode.js"
 
 /**
@@ -181,6 +182,12 @@ export const globalSettingsSchema = z.object({
 	customModes: z.array(modeConfigSchema).optional(),
 	customModePrompts: customModePromptsSchema.optional(),
 	customSupportPrompts: customSupportPromptsSchema.optional(),
+	/**
+	 * Global agent personality preference.
+	 * This personality will be applied across all modes unless a mode
+	 * has its own defaultPersonality set.
+	 */
+	agentPersonality: personalitySchema.optional(),
 	enhancementApiConfigId: z.string().optional(),
 	includeTaskHistoryInEnhance: z.boolean().optional(),
 	historyPreviewCollapsed: z.boolean().optional(),

packages/types/src/index.ts

@@ -17,6 +17,7 @@ export * from "./marketplace.js"
 export * from "./mcp.js"
 export * from "./message.js"
 export * from "./mode.js"
+export * from "./personality.js"
 export * from "./model.js"
 export * from "./provider-settings.js"
 export * from "./task.js"

packages/types/src/mode.ts

@@ -1,5 +1,6 @@
 import { z } from "zod"
 
+import { personalitySchema, instructionsTemplateSchema } from "./personality.js"
 import { toolGroupsSchema } from "./tool.js"
 
 /**
@@ -70,6 +71,18 @@ export const modeConfigSchema = z.object({
 	customInstructions: z.string().optional(),
 	groups: groupEntryArraySchema,
 	source: z.enum(["global", "project"]).optional(),
+	/**
+	 * Default personality for this mode.
+	 * When set, this personality will be used for the mode unless
+	 * overridden by the user's global personality preference.
+	 */
+	defaultPersonality: personalitySchema.optional(),
+	/**
+	 * Template for rendering personality-aware instructions.
+	 * When set and personality is provided, the template's {{ personality_message }}
+	 * placeholder will be replaced with the appropriate personality content.
+	 */
+	instructionsTemplate: instructionsTemplateSchema.optional(),
 })
 
 export type ModeConfig = z.infer<typeof modeConfigSchema>
@@ -131,14 +144,18 @@ export type CustomSupportPrompts = z.infer<typeof customSupportPromptsSchema>
 
 /**
  * DEFAULT_MODES
+ *
+ * The built-in modes that ship with the extension. Each mode has a roleDefinition
+ * that includes explicit identity disambiguation to prevent confusion with
+ * similarly-named systems or products.
  */
 
 export const DEFAULT_MODES: readonly ModeConfig[] = [
 	{
 		slug: "architect",
 		name: "🏗️ Architect",
 		roleDefinition:
-			"You are Roo, an experienced technical leader who is inquisitive and an excellent planner. Your goal is to gather information and get context to create a detailed plan for accomplishing the user's task, which the user will review and approve before they switch into another mode to implement the solution.",
+			"You are Roo, an experienced technical leader who is inquisitive and an excellent planner. Within this context, Roo refers specifically to this AI coding assistant integrated with VS Code (not any other system or product with a similar name). Your goal is to gather information and get context to create a detailed plan for accomplishing the user's task, which the user will review and approve before they switch into another mode to implement the solution.",
 		whenToUse:
 			"Use this mode when you need to plan, design, or strategize before implementation. Perfect for breaking down complex problems, creating technical specifications, designing system architecture, or brainstorming solutions before coding.",
 		description: "Plan and design before implementation",
@@ -150,7 +167,7 @@ export const DEFAULT_MODES: readonly ModeConfig[] = [
 		slug: "code",
 		name: "💻 Code",
 		roleDefinition:
-			"You are Roo, a highly skilled software engineer with extensive knowledge in many programming languages, frameworks, design patterns, and best practices.",
+			"You are Roo, a highly skilled software engineer with extensive knowledge in many programming languages, frameworks, design patterns, and best practices. Within this context, Roo refers specifically to this AI coding assistant integrated with VS Code (not any other system or product with a similar name).",
 		whenToUse:
 			"Use this mode when you need to write, modify, or refactor code. Ideal for implementing features, fixing bugs, creating new files, or making code improvements across any programming language or framework.",
 		description: "Write, modify, and refactor code",
@@ -160,7 +177,7 @@ export const DEFAULT_MODES: readonly ModeConfig[] = [
 		slug: "ask",
 		name: "❓ Ask",
 		roleDefinition:
-			"You are Roo, a knowledgeable technical assistant focused on answering questions and providing information about software development, technology, and related topics.",
+			"You are Roo, a knowledgeable technical assistant focused on answering questions and providing information about software development, technology, and related topics. Within this context, Roo refers specifically to this AI coding assistant integrated with VS Code (not any other system or product with a similar name).",
 		whenToUse:
 			"Use this mode when you need explanations, documentation, or answers to technical questions. Best for understanding concepts, analyzing existing code, getting recommendations, or learning about technologies without making changes.",
 		description: "Get answers and explanations",
@@ -172,7 +189,7 @@ export const DEFAULT_MODES: readonly ModeConfig[] = [
 		slug: "debug",
 		name: "🪲 Debug",
 		roleDefinition:
-			"You are Roo, an expert software debugger specializing in systematic problem diagnosis and resolution.",
+			"You are Roo, an expert software debugger specializing in systematic problem diagnosis and resolution. Within this context, Roo refers specifically to this AI coding assistant integrated with VS Code (not any other system or product with a similar name).",
 		whenToUse:
 			"Use this mode when you're troubleshooting issues, investigating errors, or diagnosing problems. Specialized in systematic debugging, adding logging, analyzing stack traces, and identifying root causes before applying fixes.",
 		description: "Diagnose and fix software issues",
@@ -184,7 +201,7 @@ export const DEFAULT_MODES: readonly ModeConfig[] = [
 		slug: "orchestrator",
 		name: "🪃 Orchestrator",
 		roleDefinition:
-			"You are Roo, a strategic workflow orchestrator who coordinates complex tasks by delegating them to appropriate specialized modes. You have a comprehensive understanding of each mode's capabilities and limitations, allowing you to effectively break down complex problems into discrete tasks that can be solved by different specialists.",
+			"You are Roo, a strategic workflow orchestrator who coordinates complex tasks by delegating them to appropriate specialized modes. Within this context, Roo refers specifically to this AI coding assistant integrated with VS Code (not any other system or product with a similar name). You have a comprehensive understanding of each mode's capabilities and limitations, allowing you to effectively break down complex problems into discrete tasks that can be solved by different specialists.",
 		whenToUse:
 			"Use this mode for complex, multi-step projects that require coordination across different specialties. Ideal when you need to break down large tasks into subtasks, manage workflows, or coordinate work that spans multiple domains or expertise areas.",
 		description: "Coordinate tasks across multiple modes",

packages/types/src/personality.ts

@@ -0,0 +1,175 @@
+import { z } from "zod"
+
+/**
+ * Personality enum defines the available communication styles for the agent.
+ * Each personality represents a distinct approach to interacting with users,
+ * allowing for customizable agent behavior while maintaining consistent capabilities.
+ *
+ * @remarks
+ * Personalities affect only the communication style and tone, not the agent's
+ * technical abilities or available tools. A friendly agent and a pragmatic agent
+ * have the same capabilities, but differ in how they present information.
+ *
+ * @example
+ * ```typescript
+ * import { Personality } from "@roo-code/types"
+ *
+ * const userPreference: Personality = Personality.Friendly
+ * ```
+ */
+export enum Personality {
+	/**
+	 * Warm, supportive, and team-oriented communication style.
+	 * Uses encouraging language, acknowledges user efforts, and creates
+	 * a collaborative atmosphere.
+	 */
+	Friendly = "friendly",
+
+	/**
+	 * Direct, efficient, and results-focused communication style.
+	 * Minimizes pleasantries in favor of clear, actionable information
+	 * and concise responses.
+	 */
+	Pragmatic = "pragmatic",
+}
+
+/**
+ * Zod schema for validating Personality enum values.
+ * Use this for runtime validation of personality settings.
+ *
+ * @example
+ * ```typescript
+ * const result = personalitySchema.safeParse("friendly")
+ * if (result.success) {
+ *   // result.data is Personality.Friendly
+ * }
+ * ```
+ */
+export const personalitySchema = z.nativeEnum(Personality)
+
+/**
+ * Type representing a mapping from each personality to its associated message content.
+ * Used for storing personality-specific prompts, greetings, or other text content.
+ *
+ * @remarks
+ * This type ensures that all defined personalities have corresponding message content,
+ * preventing incomplete personality configurations.
+ *
+ * @example
+ * ```typescript
+ * const greetings: PersonalityMessages = {
+ *   [Personality.Friendly]: "Hey there! I'm excited to help you today!",
+ *   [Personality.Pragmatic]: "Ready. What do you need?"
+ * }
+ * ```
+ */
+export type PersonalityMessages = Record<Personality, string>
+
+/**
+ * Array of all available personality values.
+ * Useful for iteration, validation, and UI components that need to display all options.
+ *
+ * @example
+ * ```typescript
+ * PERSONALITIES.forEach(personality => {
+ *   console.log(`Available: ${personality}`)
+ * })
+ * ```
+ */
+export const PERSONALITIES = Object.values(Personality) as Personality[]
+
+/**
+ * Default personality used when no user preference is set.
+ */
+export const DEFAULT_PERSONALITY = Personality.Friendly
+
+/**
+ * Zod schema for validating PersonalityMessages.
+ * Ensures all personality keys are present.
+ */
+export const personalityMessagesSchema = z.record(personalitySchema, z.string())
+
+/**
+ * Zod schema for validating InstructionsTemplate.
+ */
+export const instructionsTemplateSchema = z.object({
+	/** Template string containing {{ personality_message }} placeholder */
+	template: z.string(),
+	/** Optional map of personality identifiers to personality-specific instruction fragments */
+	personality_messages: personalityMessagesSchema.optional(),
+})
+
+/**
+ * Interface representing a template for rendering personality-aware instructions.
+ * Templates can contain `{{ personality_message }}` placeholders that will be
+ * substituted with personality-specific content at runtime.
+ *
+ * @remarks
+ * When `personality_messages` is not provided, the system will attempt to load
+ * personality content from the default markdown files in the personalities directory.
+ *
+ * @example
+ * ```typescript
+ * const template: InstructionsTemplate = {
+ *   template: "You are an assistant.\n\n{{ personality_message }}\n\nBe helpful.",
+ *   personality_messages: {
+ *     [Personality.Friendly]: "Be warm and encouraging!",
+ *     [Personality.Pragmatic]: "Be direct and efficient."
+ *   }
+ * }
+ * ```
+ */
+export type InstructionsTemplate = z.infer<typeof instructionsTemplateSchema>
+
+/**
+ * Zod schema for validating PersonalityUpdateMessage role.
+ * Restricts to "system" or "developer" roles.
+ */
+export const personalityUpdateMessageRoleSchema = z.enum(["system", "developer"])
+
+/**
+ * Zod schema for validating PersonalityUpdateMessage.
+ */
+export const personalityUpdateMessageSchema = z.object({
+	/**
+	 * The role for the message. Use "system" for most APIs,
+	 * "developer" for APIs that support developer messages.
+	 */
+	role: personalityUpdateMessageRoleSchema,
+	/**
+	 * The content containing the personality update instructions,
+	 * wrapped in `<personality_spec>` tags.
+	 */
+	content: z.string(),
+})
+
+/**
+ * Message structure for mid-session personality updates.
+ *
+ * This message type is injected into the conversation when the user
+ * changes their personality preference mid-session, allowing the agent
+ * to adopt a new communication style without regenerating the entire
+ * system prompt.
+ *
+ * The role should be "system" or "developer" depending on the API being used:
+ * - "system": For APIs that support system messages (OpenAI, most providers)
+ * - "developer": For APIs that use developer messages (some Anthropic contexts)
+ *
+ * @remarks
+ * This is a lightweight approach to personality changes that avoids
+ * regenerating the entire system prompt. The message is injected into
+ * the conversation history to guide the model's communication style.
+ *
+ * @example
+ * ```typescript
+ * const updateMessage: PersonalityUpdateMessage = {
+ *   role: "system",
+ *   content: `<personality_spec>
+ * The user has requested a new communication style.
+ *
+ * Be warm and encouraging...
+ * </personality_spec>`
+ * }
+ * ```
+ */
+export type PersonalityUpdateMessage = z.infer<typeof personalityUpdateMessageSchema>

packages/types/src/vscode-extension-host.ts

@@ -595,6 +595,7 @@ export interface WebviewMessage {
 		| "refreshCustomTools"
 		| "requestModes"
 		| "switchMode"
+		| "changePersonality"
 		| "debugSetting"
 		// Worktree messages
 		| "listWorktrees"
@@ -629,6 +630,7 @@ export interface WebviewMessage {
 	alwaysAllow?: boolean
 	isEnabled?: boolean
 	mode?: string
+	personality?: string
 	promptMode?: string | "enhance"
 	customPrompt?: PromptComponent
 	dataUrls?: string[]