@gitkraken/core-gitlens 0.1.0 → 0.3.0

package/src/plus/agents/types.ts

@@ -0,0 +1,277 @@
+import type { IpcHandler } from '../../ipc/ipcServer.js';
+import type { UnifiedDisposable } from '../../utils/disposable.js';
+import type { Event } from '../../utils/event.js';
+
+export const claudeCodeNonBlockingHookEvents = [
+	'SessionStart',
+	'SessionEnd',
+	'UserPromptSubmit',
+	'PreToolUse',
+	'PostToolUse',
+	'PostToolUseFailure',
+	'Notification',
+	'Stop',
+	'StopFailure',
+	'SubagentStart',
+	'SubagentStop',
+	'TeammateIdle',
+	'TaskCompleted',
+	'InstructionsLoaded',
+	'ConfigChange',
+	'WorktreeCreate',
+	'WorktreeRemove',
+	'PreCompact',
+	'PostCompact',
+	'Elicitation',
+	'ElicitationResult',
+	'PermissionDenied',
+	'CwdChanged',
+] as const;
+
+export const claudeCodeBlockingHookEvents = ['PermissionRequest'] as const;
+
+export type ClaudeCodeHookEvent =
+	| (typeof claudeCodeNonBlockingHookEvents)[number]
+	| (typeof claudeCodeBlockingHookEvents)[number];
+
+export type PermissionDecision = 'allow' | 'deny';
+
+export type AgentSessionStatus =
+	| 'thinking'
+	| 'tool_use'
+	| 'responding'
+	| 'waiting'
+	| 'idle'
+	| 'compacting'
+	| 'permission_requested';
+
+export type AgentSessionPhase = 'idle' | 'working' | 'waiting';
+
+export function getPhaseForStatus(status: AgentSessionStatus): AgentSessionPhase {
+	switch (status) {
+		case 'thinking':
+		case 'tool_use':
+		case 'responding':
+		case 'compacting':
+			return 'working';
+		case 'waiting':
+		case 'permission_requested':
+			return 'waiting';
+		case 'idle':
+			return 'idle';
+	}
+}
+
+/**
+ * Returns whether the given phase represents an agent that is actively doing work or
+ * awaiting input (as opposed to fully idle). Uses an explicit allowlist so new phases
+ * default to "not active" rather than being silently treated as live.
+ */
+export function isActiveAgentPhase(phase: AgentSessionPhase): boolean {
+	return phase === 'working' || phase === 'waiting';
+}
+
+export interface PermissionSuggestion {
+	readonly type: string;
+	readonly tool?: string;
+	readonly rules?: readonly { readonly toolName: string; readonly ruleContent?: string }[];
+	readonly destination?: string;
+}
+
+/** Classification of what the agent is awaiting input for. Drives kind-aware UI: action button
+ *  labels, phase wording, and which payload field carries the body. Detected at the provider
+ *  boundary from the tool name / event so webviews don't grow their own classifiers.
+ *  - `tool`: a regular tool permission (Bash, Edit, Read, …) — body is `toolDescription`.
+ *  - `plan`: ExitPlanMode — body is `planSummary`; `planFilePath` may link the written plan.
+ *  - `question`: AskUserQuestion — body is `questionText`; `questionCount` describes the batch.
+ *  - `elicitation`: MCP elicitation — body is just `toolName`; user must respond in-session. */
+export type PendingPermissionKind = 'tool' | 'plan' | 'question' | 'elicitation';
+
+export interface PendingPermission {
+	readonly kind: PendingPermissionKind;
+	readonly toolName: string;
+	readonly toolDescription: string;
+	readonly toolInputDescription?: string;
+	readonly suggestions?: readonly PermissionSuggestion[];
+	/** Plan-mode (`kind === 'plan'`): on-disk path of the plan markdown, when the agent wrote one. */
+	readonly planFilePath?: string;
+	/** Plan-mode: short summary extracted from the plan content (first heading or leading sentence). */
+	readonly planSummary?: string;
+	/** Question-mode (`kind === 'question'`): the leading question text. */
+	readonly questionText?: string;
+	/** Question-mode: total number of questions in the batch. */
+	readonly questionCount?: number;
+}
+
+export interface AgentSession {
+	readonly id: string;
+	readonly providerId: string;
+	readonly providerName: string;
+	readonly name?: string;
+	readonly status: AgentSessionStatus;
+	readonly phase: AgentSessionPhase;
+	readonly statusDetail?: string;
+	readonly worktreePath?: string;
+	/** Common (parent) repo path shared by every worktree in this session's repo. Set together
+	 *  with `worktreePath` by `resolveGitInfo` — equal to `worktreePath` for a default-worktree
+	 *  session, otherwise the parent repo's common path. Use this for "same repo" identity
+	 *  checks; {@link workspacePath} is the matched workspace folder, not repo identity.
+	 *
+	 *  `undefined` carries two meanings the host distinguishes internally (via the
+	 *  `gitInfoUnresolvable` bookkeeping flag) but consumers should treat identically: either
+	 *  "not yet resolved" (no probe completed) or "resolved but cwd is not inside any git repo".
+	 *  Either way, no repo identity is available — never attempt to `path.join`/`path.resolve`
+	 *  against it without an explicit `!= null` check. */
+	readonly commonPath?: string;
+	readonly pid?: number;
+	readonly lastActivity: Date;
+	readonly phaseSince: Date;
+	readonly isSubagent: boolean;
+	readonly parentId?: string;
+	readonly subagents?: readonly AgentSession[];
+	readonly pendingPermission?: PendingPermission;
+	/** The VS Code workspace folder containing the agent's cwd, or `undefined` if cwd is outside
+	 *  any open workspace folder. Used for `isInWorkspace` and "Open Folder" only — NOT for repo
+	 *  identity. For "what repo is this session in", use {@link commonPath}. */
+	readonly workspacePath?: string;
+	readonly cwd?: string;
+	readonly planFile?: string;
+	readonly isInWorkspace: boolean;
+	readonly lastPrompt?: string;
+	readonly firstPrompt?: string;
+	/** Absolute paths of files targeted by in-flight file-editing tool calls (Edit/Write/MultiEdit/
+	 *  NotebookEdit). Populated on PreToolUse, drained on PostToolUse/PermissionDenied, cleared on
+	 *  Stop/SessionEnd. Empty/undefined when no file-editing tool is active.
+	 *
+	 *  Mutable array form so `Shape<AgentSession>` projects it as `string[]` (the `Shape<>` type
+	 *  mangles `readonly T[]` into a mapped object that loses its iterator). Treat as immutable. */
+	currentFiles?: string[];
+	/** Absolute paths of files the agent recently *read* (Read/NotebookRead). Populated on
+	 *  PreToolUse, drained on PostToolUse/PermissionDenied with the same cooldown as
+	 *  `currentFiles`. Distinct from `currentFiles` which tracks write-class tools so consumers can
+	 *  visualize "looking at" vs "working on" differently. Treat as immutable. */
+	currentReads?: string[];
+	/** `true` when the session was discovered via peer IPC sync (i.e. another GitLens window hosts
+	 *  the agent's hook flow and Claude Code extension panel). Locally-owned sessions leave this
+	 *  unset. The dispatcher uses this to route opens through the peer's IPC route + an OS-level
+	 *  window focus, since calling `claude-vscode.editor.open` in *our* extension only opens an
+	 *  inert local view that isn't connected to the live session running in the peer.
+	 *
+	 *  Window-local: never serialized faithfully across the IPC wire. Each window decides locally
+	 *  based on how it received the session — `querySiblingWindowSessions` always overrides to
+	 *  `true` regardless of what the peer published. */
+	readonly isPeerOwned?: boolean;
+	/**
+	 * Titles discovered by tailing the Claude Code transcript JSONL at
+	 * `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`. Populated by
+	 * `ClaudeCodeTranscriptReader`; used by `getSessionDisplayName` as a fallback when no
+	 * harness-supplied `name` is available. Last occurrence in the transcript wins per type.
+	 */
+	readonly transcriptTitles?: {
+		readonly custom?: string;
+		readonly ai?: string;
+		readonly agent?: string;
+	};
+}
+
+export interface AgentSessionProvider extends UnifiedDisposable {
+	readonly id: string;
+	readonly name: string;
+	readonly icon: string;
+
+	readonly onDidChangeSessions: Event<void>;
+	readonly sessions: readonly AgentSession[];
+
+	start(workspacePaths: string[]): void;
+	stop(): void;
+	updateWorkspacePaths?(workspacePaths: string[]): void;
+
+	/** Resolves a pending permission. Returns `true` when the resolve was routed (the local IPC
+	 *  owns the session's pending entry); `false` when no local entry exists (typically a peer-
+	 *  discovered session owned by another GitLens window). Callers use this to give the user
+	 *  feedback rather than a silent no-op. */
+	resolvePermission?(
+		sessionId: string,
+		decision: PermissionDecision,
+		updatedPermissions?: PermissionSuggestion[],
+	): boolean;
+
+	/** Asks the peer GitLens window that has `workspacePath` open (or any peer whose workspacePath
+	 *  contains, or is contained by, it) to open the given session in its Claude Code extension
+	 *  via the `agents/sessions/open` IPC route. Resolves to `true` when at least one peer claimed
+	 *  the workspace AND was reachable; `false` otherwise. Best-effort: never rejects. The boolean
+	 *  is currently a diagnostic signal only — the dispatcher fires this in parallel with
+	 *  `vscode.openFolder` and relies on VS Code's window-folder matching to focus the owning
+	 *  window (which works whether or not the peer runs GitLens). */
+	notifyPeerOpenSession?(workspacePath: string, sessionId: string): Promise<boolean>;
+}
+
+/**
+ * Host-supplied IPC service. The agents package registers handlers and publishes
+ * the agents discovery file via this interface so it doesn't depend on the host's
+ * IPC service directly.
+ *
+ * The agents package is the source of truth for the workspacePaths advertised in
+ * the agents discovery file — `publishAgents` takes them as an argument and the host
+ * is expected to re-publish whenever those paths change.
+ */
+export interface IpcRegistrar {
+	readonly port: number | undefined;
+	/** Directory scanned for peer-window agent discovery files. Omit to disable peer discovery (tests). */
+	readonly agentDiscoveryDir?: string;
+	registerHandler<Request = unknown, Response = unknown>(
+		name: string,
+		handler: IpcHandler<Request, Response>,
+	): UnifiedDisposable;
+	publishAgents(workspacePaths: string[]): Promise<void>;
+	unpublishAgents(): Promise<void>;
+}
+
+export interface AgentProviderCallbacks {
+	/** Host-supplied IPC service. Required for agents to receive hook events from the GK CLI. */
+	ipc: IpcRegistrar;
+
+	/** Report that an agent session started. No-op if the host has no telemetry. */
+	onSessionStarted?(provider: string): void;
+
+	/** Report that an agent session ended. No-op if the host has no telemetry. */
+	onSessionEnded?(provider: string): void;
+
+	/** Report that a permission request was resolved. No-op if the host has no telemetry. */
+	onPermissionResolved?(info: { provider: string; tool: string; decision: PermissionDecision }): void;
+
+	/** Notify the host that a branch has agent activity. */
+	onBranchAgentActivity?(cwd: string): void;
+
+	/**
+	 * Run the GK CLI with the given args. Returns stdout.
+	 *
+	 * Host responsibilities:
+	 * - Resolve the CLI executable path (e.g. via `resolveCLIExecutable`)
+	 * - Provide the default `cwd` if `options.cwd` is not set (e.g. `globalStorageUri.fsPath` in VS Code)
+	 * - Inject any environment-specific flags (e.g. `--insiders` when the host has insiders mode enabled)
+	 */
+	runCLICommand(args: string[], options?: { cwd?: string }): Promise<string>;
+
+	/**
+	 * Resolve git metadata for a session's cwd. Returns the stable worktree path; the worktree's
+	 * display name (branch name for branch-type worktrees) is intentionally NOT returned — it's
+	 * resolved live at serialization time so `git checkout` updates display without restarting.
+	 * Optional — if omitted, sessions won't have worktree metadata.
+	 */
+	resolveGitInfo?(cwd: string): Promise<
+		| {
+				repoRoot: string;
+				isWorktree: boolean;
+				worktreePath?: string;
+		  }
+		| undefined
+	>;
+
+	/**
+	 * Open a Claude Code session in the Claude Code VS Code extension. Invoked by the IPC handler
+	 * when a peer GitLens window asks this window to open a session on its behalf — the host wires
+	 * this to `claude-vscode.editor.open`. Throws if the extension isn't installed/active.
+	 */
+	openSessionInClaudeExtension?(sessionId: string): Promise<void>;
+}

package/src/plus/ai/constants.ts

@@ -13,6 +13,7 @@ export type AIProviders =
 	| 'openai'
 	| 'openaicompatible'
 	| 'openrouter'
+	| 'simulator'
 	| 'vscode'
 	| 'xai';
 export type AIPrimaryProviders = Extract<AIProviders, 'gitkraken' | 'vscode'>;
@@ -119,3 +120,10 @@ export const ollamaProviderDescriptor: AIProviderDescriptor<'ollama'> = {
 	requiresAccount: true,
 	requiresUserKey: false,
 } as const;
+export const simulatorProviderDescriptor: AIProviderDescriptor<'simulator'> = {
+	id: 'simulator',
+	name: 'Simulator (Debugging)',
+	primary: false,
+	requiresAccount: false,
+	requiresUserKey: false,
+} as const;

package/src/plus/ai/errors.ts

@@ -10,6 +10,8 @@ export const enum AIErrorReason {
 	ServiceCapacityExceeded,
 	Unauthorized,
 	UserQuotaExceeded,
+	NoNetwork,
+	Unreachable,
 }
 
 export class AIError extends Error {
@@ -37,6 +39,12 @@ export class AIError extends Error {
 			case AIErrorReason.ServiceCapacityExceeded:
 				message = 'Service capacity exceeded';
 				break;
+			case AIErrorReason.NoNetwork:
+				message = 'Unable to reach the AI service. Please check your internet connection.';
+				break;
+			case AIErrorReason.Unreachable:
+				message = 'The AI service is temporarily unreachable.';
+				break;
 			case AIErrorReason.NoRequestData:
 				message = original?.message ?? 'No data was provided for the request';
 				break;
@@ -80,3 +88,35 @@ export class AINoRequestDataError extends AIError {
 		Error.captureStackTrace?.(this, new.target);
 	}
 }
+
+const noNetworkErrorCodes = new Set([
+	'ENOTFOUND',
+	'ECONNREFUSED',
+	'EAI_AGAIN',
+	'EHOSTUNREACH',
+	'ENETUNREACH',
+	'ENETDOWN',
+	'UND_ERR_CONNECT_TIMEOUT',
+]);
+
+const unreachableErrorCodes = new Set(['ECONNRESET', 'ETIMEDOUT', 'UND_ERR_SOCKET']);
+
+export function classifyNetworkError(ex: unknown): AIErrorReason.NoNetwork | AIErrorReason.Unreachable | undefined {
+	let current: unknown = ex;
+	let sawFetchFailed = false;
+	for (let depth = 0; depth < 5 && current != null; depth++) {
+		if (!(current instanceof Error)) break;
+
+		if (current.name === 'TypeError' && current.message === 'fetch failed') {
+			sawFetchFailed = true;
+		}
+		const code = (current as { code?: unknown }).code;
+		if (typeof code === 'string') {
+			if (noNetworkErrorCodes.has(code)) return AIErrorReason.NoNetwork;
+			if (unreachableErrorCodes.has(code)) return AIErrorReason.Unreachable;
+		}
+
+		current = (current as { cause?: unknown }).cause;
+	}
+	return sawFetchFailed ? AIErrorReason.NoNetwork : undefined;
+}

package/src/plus/ai/models/model.ts

@@ -22,6 +22,7 @@ export interface AIModelDescriptor<Provider extends AIProviders = AIProviders, M
 
 export type AIActionType =
 	| 'explain-changes'
+	| 'review-changes'
 	| 'generate-commitMessage'
 	| 'generate-stashMessage'
 	| 'generate-changelog'

package/src/plus/ai/models/promptTemplates.ts

@@ -78,6 +78,36 @@ interface ReviewPullRequestPromptTemplateContext {
 	instructions?: string;
 }
 
+interface ReviewChangesPromptTemplateContext {
+	diff: string;
+	message: string;
+	context?: string;
+	instructions?: string;
+}
+
+interface ReviewOverviewPromptTemplateContext {
+	files: string;
+	message: string;
+	context?: string;
+	instructions?: string;
+}
+
+interface ReviewDetailPromptTemplateContext {
+	diff: string;
+	overview: string;
+	message: string;
+	focusArea: string;
+	context?: string;
+	instructions?: string;
+}
+
+interface AddressReviewFindingsPromptTemplateContext {
+	reviewMarkdown: string;
+	scopeLabel: string;
+	granularity: 'review' | 'focusArea' | 'finding';
+	instructions?: string;
+}
+
 interface StartWorkIssuePromptTemplateContext {
 	issue: string;
 	instructions?: string;
@@ -91,6 +121,10 @@ export type PromptTemplateType =
 	| 'generate-commits'
 	| 'generate-searchQuery'
 	| 'explain-changes'
+	| 'review-changes'
+	| 'review-overview'
+	| 'review-detail'
+	| 'address-review-findings'
 	| 'start-review-pullRequest'
 	| 'start-work-issue';
 
@@ -115,6 +149,14 @@ export type PromptTemplateContext<T extends PromptTemplateType> = T extends 'gen
 	? SearchQueryPromptTemplateContext
 	: T extends 'explain-changes'
 	? ExplainChangesPromptTemplateContext
+	: T extends 'review-changes'
+	? ReviewChangesPromptTemplateContext
+	: T extends 'review-overview'
+	? ReviewOverviewPromptTemplateContext
+	: T extends 'review-detail'
+	? ReviewDetailPromptTemplateContext
+	: T extends 'address-review-findings'
+	? AddressReviewFindingsPromptTemplateContext
 	: T extends 'start-review-pullRequest'
 	? ReviewPullRequestPromptTemplateContext
 	: T extends 'start-work-issue'

package/src/plus/ai/models/results.ts

@@ -1 +1,31 @@
 export type AISummarizedResult = { summary: string; body: string };
+
+export type AIReviewSeverity = 'critical' | 'warning' | 'suggestion';
+
+export interface AIReviewFinding {
+	readonly id: string;
+	readonly severity: AIReviewSeverity;
+	readonly title: string;
+	readonly description: string;
+	readonly filePath?: string;
+	readonly lineRange?: { readonly start: number; readonly end: number };
+}
+
+export interface AIReviewFocusArea {
+	readonly id: string;
+	readonly label: string;
+	readonly rationale: string;
+	readonly severity: AIReviewSeverity;
+	readonly files: readonly string[];
+	readonly findings?: readonly AIReviewFinding[];
+}
+
+export interface AIReviewResult {
+	readonly overview: string;
+	readonly focusAreas: readonly AIReviewFocusArea[];
+	readonly mode: 'single-pass' | 'two-pass';
+}
+
+export interface AIReviewDetailResult {
+	readonly findings: readonly AIReviewFinding[];
+}

package/src/plus/ai/prompts.ts

@@ -350,7 +350,7 @@ Available search operators:
 - 'commit:' - Search by a specific commit SHA (e.g. 'commit:4ce3a')
 - 'file:' - Search by file path (e.g. 'file:"package.json"', 'file:"*.ts"'); maps to \`git log -- <value>\`
 - 'change:' - Search by specific code changes using regular expressions (e.g. 'change:"function.*auth"', 'change:"import.*react"'); maps to \`git log -G<value>\`
-- 'type:' - Search by type -- supports stash and tip (e.g. 'type:stash', 'type:tip')
+- 'type:' - Search by type -- supports stash, tip, and wip (e.g. 'type:stash', 'type:tip', 'type:wip'). Use 'type:wip' for queries about work in progress, uncommitted changes, or pending changes across worktrees.
 - 'ref:' - Search for commits reachable by a reference (branch, tag, commit) or reference range. Supports single refs (e.g. 'ref:main', 'ref:v1.0'), two-dot ranges (e.g. 'ref:main..feature' for commits in feature but not in main), three-dot ranges (e.g. 'ref:main...feature' for symmetric difference), and relative refs (e.g. 'ref:HEAD~5..HEAD'); maps to \`git log <ref>\`
 - 'after:' - Search for commits after a certain date or range (e.g. 'after:2023-01-01', 'after:"6 months ago"', 'after:"last Tuesday"', 'after:"noon"', 'after:"1 month 2 days ago"'); maps to \`git log --since=<value>\`
 - 'before:' - Search for commits before a certain date or range (e.g. 'before:2023-01-01', 'before:"6 months ago"', 'before:"yesterday"', 'before:"3PM GMT"'); maps to \`git log --until=<value>\`
@@ -526,3 +526,173 @@ You can use GitKraken MCP tools to gather additional context about the repositor
 
 Now, proceed with your analysis and provide a comprehensive review of the PR. Return only the relevant information without any additional text.`,
 };
+
+export const reviewChanges: PromptTemplate<'review-changes'> = {
+	id: 'review-changes',
+	variables: ['diff', 'message', 'context', 'instructions'],
+	template: `You are an expert code reviewer analyzing a set of code changes. Your goal is to identify meaningful issues — bugs, logic errors, security vulnerabilities, missing error handling, and potential regressions — while ignoring style preferences and linter-level concerns. Focus on problems a careful human reviewer would catch.
+
+Examine the following code changes in Git diff format. Each non-header line inside a hunk has been annotated with its 1-based new-file line number in a \`[NNNNN]\` block placed immediately after the line-type marker (\` \`, \`+\`, or \`-\`):
+  \` [   42] context line\`     // context: exists in both old and new; number = new-file line
+  \`+[   43] added line\`        // added: only in new file; number = new-file line
+  \`-[     ] removed line\`      // removed: not in new file; brackets are blank
+  \`@@ -10,5 +12,7 @@ ...\`     // hunk header (no annotation; ignore for line citing)
+<~~diff~~>
+\${diff}
+</~~diff~~>
+
+Author's description of the changes:
+<~~message~~>
+\${message}
+</~~message~~>
+
+Related work items (known pull requests and issues for this change set). Use these for *intent*: what the change is trying to accomplish. They are not authoritative spec — if a finding contradicts the stated intent, flag it rather than defer to it. May be empty.
+\${context}
+
+Produce a structured review in the following XML format. Include ONLY the XML tags described — no other text:
+
+<overview>
+A concise 1-3 sentence summary of what these changes do and their overall quality. Note any systemic concerns.
+</overview>
+<focus-areas>
+<area severity="critical|warning|suggestion" files="comma-separated file paths">
+<label>Short title of the concern (under 60 chars)</label>
+<rationale>Why this matters — what could go wrong or what is suboptimal</rationale>
+<findings>
+<finding severity="critical|warning|suggestion" file="path/to/file.ts" lines="start-end">
+<title>Specific issue title</title>
+<description>Clear explanation of the problem and how to address it</description>
+</finding>
+</findings>
+</area>
+</focus-areas>
+
+Guidelines:
+- Severity levels: "critical" = bugs, security issues, data loss risks; "warning" = logic concerns, missing error handling, potential regressions; "suggestion" = improvements, maintainability, performance
+- Group related findings into focus areas by theme, not by file
+- If changes look correct and well-structured, say so in the overview and include zero focus areas
+- 3-5 high-quality findings are better than 15 low-quality ones
+- For \`lines="start-end"\`, copy the numbers from the \`[NNNNN]\` annotations of the specific lines your finding concerns. Do not count, infer, or estimate — use only the annotated numbers. Removed lines (blank brackets \`[     ]\`) cannot be cited; pick the nearest surrounding new-file line instead. Anchor the range tightly to the lines the finding actually concerns; do not span an entire hunk.
+- Do not flag style issues, naming preferences, or things a linter would catch
+- Base conclusions only on the code shown — do not speculate about unseen code
+
+\${instructions}
+
+Review the changes and produce the structured XML output above.`,
+};
+
+export const reviewOverview: PromptTemplate<'review-overview'> = {
+	id: 'review-overview',
+	variables: ['files', 'message', 'context', 'instructions'],
+	template: `You are an expert code reviewer performing an initial assessment of a set of code changes. You are given a file manifest (not full diffs) — use the file paths, change types, and line counts to identify which areas deserve closer inspection.
+
+File manifest (JSON array of changed files):
+<~~files~~>
+\${files}
+</~~files~~>
+
+Author's description of the changes:
+<~~message~~>
+\${message}
+</~~message~~>
+
+Related work items (known pull requests and issues for this change set). Use these for *intent* — what the change is trying to accomplish — when ranking which areas deserve closer review. May be empty.
+\${context}
+
+Produce a structured assessment in the following XML format. Include ONLY the XML tags described — no other text:
+
+<overview>
+A concise 1-3 sentence summary of the scope and nature of these changes based on the file manifest and description.
+</overview>
+<focus-areas>
+<area severity="critical|warning|suggestion" files="comma-separated file paths">
+<label>Short title of the area to inspect (under 60 chars)</label>
+<rationale>Why this area deserves closer review — based on the types of files changed, the volume of changes, and potential risk</rationale>
+</area>
+</focus-areas>
+
+Guidelines:
+- Severity reflects potential risk: "critical" = security-sensitive files, auth/crypto/payment paths, database migrations; "warning" = core logic changes, API changes, large modifications; "suggestion" = refactoring, config changes, documentation
+- Rank focus areas from highest to lowest risk
+- Group related files into focus areas by theme
+- Include 2-6 focus areas. If changes are very simple, fewer is fine
+- Do NOT include <findings> — those come in a later pass when full diffs are available
+
+\${instructions}
+
+Assess the changes and produce the structured XML output above.`,
+};
+
+export const addressReviewFindings: PromptTemplate<'address-review-findings'> = {
+	id: 'address-review-findings',
+	variables: ['reviewMarkdown', 'scopeLabel', 'granularity', 'instructions'],
+	template: `You are an AI coding agent tasked with addressing the issues identified in a code review. Your goal is to understand each finding and, where appropriate, propose or make the code changes needed to fix it.
+
+The review was performed against: \${scopeLabel}
+
+The findings are provided as structured markdown below. Each finding includes a severity (\`**[CRITICAL]**\`, \`**[WARNING]**\`, or \`**[SUGGESTION]**\`), a short title, a description of the problem, and (when available) a file path and line range. Focus areas group related findings and include a rationale explaining why they matter.
+
+<review>
+\${reviewMarkdown}
+</review>
+
+Guidelines:
+- Treat the findings as a working list. Prioritize critical issues, then warnings, then suggestions.
+- For each finding, locate the referenced file(s) in the workspace before proposing a fix. If the file or line range no longer matches the review (the code may have evolved), reconcile against the current state.
+- When making code changes, address the underlying problem the finding describes — do not just paper over symptoms.
+- Prefer minimal, focused edits that don't introduce unrelated changes.
+- If a finding is ambiguous, contradicts the surrounding code's intent, or is already addressed in the current state, say so explicitly rather than fabricating a fix.
+- If a finding is out of scope (touches unrelated systems, requires significant refactoring, or contradicts established patterns), surface that as a tradeoff rather than acting on it.
+
+\${instructions}`,
+};
+
+export const reviewDetail: PromptTemplate<'review-detail'> = {
+	id: 'review-detail',
+	variables: ['diff', 'overview', 'message', 'focusArea', 'context', 'instructions'],
+	template: `You are an expert code reviewer performing a detailed inspection of specific files that were flagged for closer review. You have the context from an initial overview assessment.
+
+Initial overview of the full changeset:
+<~~overview~~>
+\${overview}
+</~~overview~~>
+
+Focus area being inspected: \${focusArea}
+
+Author's description of the changes:
+<~~message~~>
+\${message}
+</~~message~~>
+
+Related work items (known pull requests and issues for this change set). Use these for *intent* — what the change is trying to accomplish. They are not authoritative spec; if a finding contradicts the stated intent, flag it. May be empty.
+\${context}
+
+Code changes for the files in this focus area (Git diff format). Each non-header line inside a hunk has been annotated with its 1-based new-file line number in a \`[NNNNN]\` block placed immediately after the line-type marker (\` \`, \`+\`, or \`-\`):
+  \` [   42] context line\`     // context: exists in both old and new; number = new-file line
+  \`+[   43] added line\`        // added: only in new file; number = new-file line
+  \`-[     ] removed line\`      // removed: not in new file; brackets are blank
+  \`@@ -10,5 +12,7 @@ ...\`     // hunk header (no annotation; ignore for line citing)
+<~~diff~~>
+\${diff}
+</~~diff~~>
+
+Produce detailed findings in the following XML format. Include ONLY the XML tags — no other text:
+
+<findings>
+<finding severity="critical|warning|suggestion" file="path/to/file.ts" lines="start-end">
+<title>Specific issue title</title>
+<description>Clear explanation of the problem and how to address it</description>
+</finding>
+</findings>
+
+Guidelines:
+- Severity: "critical" = bugs, security, data loss; "warning" = logic concerns, error handling, regressions; "suggestion" = improvements, maintainability
+- For \`lines="start-end"\`, copy the numbers from the \`[NNNNN]\` annotations of the specific lines your finding concerns. Do not count, infer, or estimate — use only the annotated numbers. Removed lines (blank brackets \`[     ]\`) cannot be cited; pick the nearest surrounding new-file line instead. Anchor the range tightly to the lines the finding actually concerns; do not span an entire hunk.
+- Be concrete — explain what the problem is and how to fix it
+- If the code in this area looks correct, return an empty <findings></findings> block
+- Do not flag style issues or things a linter would catch
+
+\${instructions}
+
+Inspect the diff for this focus area and produce the structured XML findings above.`,
+};

package/src/plus/ai/utils/ai.utils.ts

@@ -4,6 +4,8 @@ export function getActionName(action: AIActionType): string {
 	switch (action) {
 		case 'explain-changes':
 			return 'Explain Changes';
+		case 'review-changes':
+			return 'Review Changes';
 		case 'generate-commitMessage':
 			return 'Generate Commit Message';
 		case 'generate-stashMessage':