From 1f9769a93255eb16a866fe9ac3937d066e469dbd Mon Sep 17 00:00:00 2001
From: Bohdan Triapitsyn <artmore@protonmail.com>
Date: Sun, 7 Jun 2026 01:22:40 +0300
Subject: [PATCH] feat: add session review handoff flow

Introduce a desktop/web-only /handoff-review flow that generates a handoff from the active implementation session, creates or reuses a separate review session in the same directory, and links the pair through hidden OpenChamber session metadata.

Add review flow orchestration, metadata helpers, magic prompts, localized command/action labels, session metadata create/update support, and assistant message transfer actions for sending reviewer feedback back to the implementer or implementation responses back to the reviewer.

Review sessions are ordinary sessions, not child sessions. The flow avoids exposing session IDs or routing metadata to agents, hides review controls on mobile and VS Code, hides unrelated assistant actions inside review sessions, cleans up stale metadata where possible, and uses the optimistic send path so cross-session sends scroll like normal composer messages.
---
 packages/ui/src/components/chat/ChatInput.tsx |  25 +-
 .../components/chat/CommandAutocomplete.tsx   |  14 +-
 .../components/chat/message/MessageBody.tsx   | 106 ++-
 packages/ui/src/lib/i18n/messages/en.ts       |   3 +
 packages/ui/src/lib/i18n/messages/es.ts       |   3 +
 packages/ui/src/lib/i18n/messages/ko.ts       |   3 +
 packages/ui/src/lib/i18n/messages/pl.ts       |   3 +
 packages/ui/src/lib/i18n/messages/pt-BR.ts    |   3 +
 packages/ui/src/lib/i18n/messages/uk.ts       |   3 +
 packages/ui/src/lib/i18n/messages/zh-CN.ts    |   3 +
 packages/ui/src/lib/i18n/messages/zh-TW.ts    |   3 +
 packages/ui/src/lib/magicPrompts.ts           |  75 ++
 packages/ui/src/lib/opencode/client.ts        |  11 +-
 packages/ui/src/lib/reviewFlow.ts             | 235 ++++++
 packages/ui/src/lib/sessionReviewMetadata.ts  |  82 ++
 .../ui/src/stores/useGlobalSessionsStore.ts   |   1 +
 packages/ui/src/sync/session-actions.ts       |  49 ++
 packages/ui/src/sync/session-ui-store.ts      |   6 +-
 review-flow-implementation-plan.md            | 766 ++++++++++++++++++
 19 files changed, 1381 insertions(+), 13 deletions(-)
 create mode 100644 packages/ui/src/lib/reviewFlow.ts
 create mode 100644 packages/ui/src/lib/sessionReviewMetadata.ts
 create mode 100644 review-flow-implementation-plan.md

diff --git a/packages/ui/src/components/chat/ChatInput.tsx b/packages/ui/src/components/chat/ChatInput.tsx
index 3d9b7a51..0b91c32a 100644
--- a/packages/ui/src/components/chat/ChatInput.tsx
+++ b/packages/ui/src/components/chat/ChatInput.tsx
@@ -15,6 +15,7 @@ import { useInlineCommentDraftStore, type InlineCommentDraft } from '@/stores/us
 import { useSnippetsStore } from '@/stores/useSnippetsStore';
 import { appendInlineComments } from '@/lib/messages/inlineComments';
 import { renderMagicPrompt } from '@/lib/magicPrompts';
+import { startReviewFlow } from '@/lib/reviewFlow';
 import { AttachedFilesList, AttachedVSCodeFileChips, ActiveEditorFileSuggestion } from './FileAttachment';
 import ToolOutputDialog from './message/ToolOutputDialog';
 import type { ToolPopupContent } from './message/types';
@@ -1106,10 +1107,11 @@ const ChatInputComponent: React.FC<ChatInputProps> = ({ onOpenSettings, scrollTo
         const names = new Set<string>([
             'init', 'review', 'undo', 'redo', 'timeline', 'compact', 'summary', 'workspace-review', 'plan-feature', 'catch-up', 'debug', 'weigh', 'explore',
         ]);
+        if (!isMobile && !isVSCodeRuntime()) names.add('handoff-review');
         for (const command of availableCommands) names.add(command.name.toLowerCase());
         for (const skill of availableSkills) names.add(skill.name.toLowerCase());
         return names;
-    }, [availableCommands, availableSkills]);
+    }, [availableCommands, availableSkills, isMobile]);
 
     // /command and /skill spans (primary color). Only tokens that match a known
     // command/skill name are highlighted — partial/unknown tokens stay plain.
@@ -1937,6 +1939,27 @@ const ChatInputComponent: React.FC<ChatInputProps> = ({ onOpenSettings, scrollTo
                 }
                 return;
             }
+            else if (commandName === 'handoff-review' && currentSessionId && !isMobile && !isVSCodeRuntime()) {
+                try {
+                    const directory = useSessionUIStore.getState().getDirectoryForSession(currentSessionId) || currentDirectory || '';
+                    if (!directory) {
+                        throw new Error('Session directory is unavailable');
+                    }
+                    await startReviewFlow({
+                        originalSessionID: currentSessionId,
+                        directory,
+                        providerID: providerIdToSend,
+                        modelID: modelIdToSend,
+                        agent: agentNameToSend,
+                        variant: variantToSend,
+                        agentMentionName,
+                    });
+                    scrollToBottom?.();
+                } catch (error) {
+                    console.error('[review-flow] failed to start review flow', error);
+                }
+                return;
+            }
             else if (commandName === 'plan-feature' && (currentSessionId || newSessionDraftOpen)) {
                 try {
                     await sessionActions.waitForConnectionOrThrow();
diff --git a/packages/ui/src/components/chat/CommandAutocomplete.tsx b/packages/ui/src/components/chat/CommandAutocomplete.tsx
index eeed9c21..7985563b 100644
--- a/packages/ui/src/components/chat/CommandAutocomplete.tsx
+++ b/packages/ui/src/components/chat/CommandAutocomplete.tsx
@@ -7,6 +7,8 @@ import { useSkillsStore } from '@/stores/useSkillsStore';
 import { ScrollableOverlay } from '@/components/ui/ScrollableOverlay';
 import { Icon } from "@/components/icon/Icon";
 import { useI18n } from '@/lib/i18n';
+import { useUIStore } from '@/stores/useUIStore';
+import { isVSCodeRuntime } from '@/lib/desktop';
 
 type CommandSource = 'openchamber' | 'opencode' | 'skill';
 
@@ -65,6 +67,8 @@ export const CommandAutocomplete = React.forwardRef<CommandAutocompleteHandle, C
   const hasSession = Boolean(currentSessionId);
   const hasNewSessionDraft = useSessionUIStore((state) => Boolean(state.newSessionDraft?.open));
   const canStartSessionCommand = hasSession || hasNewSessionDraft;
+  const isMobile = useUIStore((state) => state.isMobile);
+  const canUseReviewHandoffFlow = hasSession && !isMobile && !isVSCodeRuntime();
 
   const [commands, setCommands] = React.useState<CommandInfo[]>([]);
   const [loading, setLoading] = React.useState(false);
@@ -152,6 +156,10 @@ export const CommandAutocomplete = React.forwardRef<CommandAutocompleteHandle, C
             ? [{ id: 'openchamber:workspace-review', name: 'workspace-review', source: 'openchamber' as const, description: t('chat.commandAutocomplete.command.workspaceReviewDescription'), isOpenChamber: true }]
             : []
           ),
+          ...(canUseReviewHandoffFlow
+            ? [{ id: 'openchamber:handoff-review', name: 'handoff-review', source: 'openchamber' as const, description: t('chat.commandAutocomplete.command.handoffReviewDescription'), isOpenChamber: true }]
+            : []
+          ),
           ...(canStartSessionCommand
             ? [{ id: 'openchamber:plan-feature', name: 'plan-feature', source: 'openchamber' as const, description: t('chat.commandAutocomplete.command.featurePlanDescription'), isOpenChamber: true }]
             : []
@@ -217,6 +225,10 @@ export const CommandAutocomplete = React.forwardRef<CommandAutocompleteHandle, C
             ? [{ id: 'openchamber:workspace-review', name: 'workspace-review', source: 'openchamber' as const, description: t('chat.commandAutocomplete.command.workspaceReviewDescription'), isOpenChamber: true }]
             : []
           ),
+          ...(canUseReviewHandoffFlow
+            ? [{ id: 'openchamber:handoff-review', name: 'handoff-review', source: 'openchamber' as const, description: t('chat.commandAutocomplete.command.handoffReviewDescription'), isOpenChamber: true }]
+            : []
+          ),
           ...(canStartSessionCommand
             ? [{ id: 'openchamber:plan-feature', name: 'plan-feature', source: 'openchamber' as const, description: t('chat.commandAutocomplete.command.featurePlanDescription'), isOpenChamber: true }]
             : []
@@ -253,7 +265,7 @@ export const CommandAutocomplete = React.forwardRef<CommandAutocompleteHandle, C
     };
 
     loadCommands();
-  }, [searchQuery, hasMessagesInCurrentSession, hasSession, canStartSessionCommand, commandsWithMetadata, skills, t]);
+  }, [searchQuery, hasMessagesInCurrentSession, hasSession, canStartSessionCommand, canUseReviewHandoffFlow, commandsWithMetadata, skills, t]);
 
   React.useEffect(() => {
     setSelectedIndex(0);
diff --git a/packages/ui/src/components/chat/message/MessageBody.tsx b/packages/ui/src/components/chat/message/MessageBody.tsx
index 79ae9f6c..1eeb8659 100644
--- a/packages/ui/src/components/chat/message/MessageBody.tsx
+++ b/packages/ui/src/components/chat/message/MessageBody.tsx
@@ -48,6 +48,12 @@ import { useI18n } from '@/lib/i18n';
 import { extractLoopbackUrls } from '@/lib/url';
 import { useDeviceInfo } from '@/lib/device';
 import { FileTypeIcon } from '@/components/icons/FileTypeIcon';
+import { useGlobalSessionsStore } from '@/stores/useGlobalSessionsStore';
+import {
+    getReviewTransferDirection,
+    sendImplementationResponseToReviewer,
+    sendReviewFeedbackToOriginal,
+} from '@/lib/reviewFlow';
 
 
 const CONTAIN_LAYOUT_STYLE = { contain: 'layout' as const, transform: 'translateZ(0)' };
@@ -641,6 +647,11 @@ interface AssistantMessageActionButtonsProps {
     hasCopyableText: boolean;
     isTouchContext: boolean;
     onCopyMessage?: () => void | boolean | Promise<void | boolean>;
+    reviewTransferAction?: {
+        ariaLabel: string;
+        tooltip: string;
+        onClick: () => void | Promise<void>;
+    };
     onShareImage: (sourceElement?: HTMLElement | null) => Promise<void>;
     ttsText: string;
 }
@@ -649,6 +660,7 @@ const AssistantMessageActionButtons = React.memo(({
     hasCopyableText,
     isTouchContext,
     onCopyMessage,
+    reviewTransferAction,
     onShareImage,
     ttsText,
 }: AssistantMessageActionButtonsProps) => {
@@ -660,6 +672,7 @@ const AssistantMessageActionButtons = React.memo(({
     const [copyHintVisible, setCopyHintVisible] = React.useState(false);
     const [isMessageCopied, setIsMessageCopied] = React.useState(false);
     const [isSharing, setIsSharing] = React.useState(false);
+    const [isTransferringReview, setIsTransferringReview] = React.useState(false);
     const copyHintTimeoutRef = React.useRef<number | null>(null);
     const copiedResetTimeoutRef = React.useRef<number | null>(null);
     const canCopyMessage = Boolean(onCopyMessage);
@@ -758,6 +771,21 @@ const AssistantMessageActionButtons = React.memo(({
         [hasCopyableText, isSharing, onShareImage]
     );
 
+    const handleReviewTransferClick = React.useCallback(
+        async (event: React.MouseEvent<HTMLButtonElement>) => {
+            event.stopPropagation();
+            event.preventDefault();
+            if (!reviewTransferAction || isTransferringReview || !hasCopyableText) return;
+            setIsTransferringReview(true);
+            try {
+                await reviewTransferAction.onClick();
+            } finally {
+                setIsTransferringReview(false);
+            }
+        },
+        [hasCopyableText, isTransferringReview, reviewTransferAction]
+    );
+
     const readAloudTooltip = React.useMemo(() => {
         if (isTTSPlaying) {
             return t('chat.messageBody.tts.stopSpeaking');
@@ -831,6 +859,34 @@ const AssistantMessageActionButtons = React.memo(({
                     <TooltipContent sideOffset={6}>{t('chat.messageBody.actions.copyAnswer')}</TooltipContent>
                 </Tooltip>
             )}
+            {reviewTransferAction && chatSurfaceMode !== 'mini-chat' ? (
+                <Tooltip>
+                    <TooltipTrigger asChild>
+                        <Button
+                            type="button"
+                            size="icon"
+                            variant="ghost"
+                            disabled={isTransferringReview || !hasCopyableText}
+                            className={cn(
+                                'h-8 w-8 text-muted-foreground bg-transparent hover:text-foreground hover:!bg-transparent active:!bg-transparent focus-visible:!bg-transparent focus-visible:ring-2 focus-visible:ring-primary/50',
+                                (!hasCopyableText || isTransferringReview) && 'opacity-50'
+                            )}
+                            aria-label={reviewTransferAction.ariaLabel}
+                            onPointerDown={(event) => event.stopPropagation()}
+                            onClick={(event) => {
+                                void handleReviewTransferClick(event);
+                            }}
+                        >
+                            {isTransferringReview ? (
+                                <Icon name="loader-4" className="h-4 w-4 animate-spin" />
+                            ) : (
+                                <Icon name="arrow-left-right" className="h-4 w-4" />
+                            )}
+                        </Button>
+                    </TooltipTrigger>
+                    <TooltipContent sideOffset={6}>{reviewTransferAction.tooltip}</TooltipContent>
+                </Tooltip>
+            ) : null}
             {chatSurfaceMode !== 'mini-chat' ? <Tooltip>
                 <TooltipTrigger asChild>
                     <Button
@@ -1065,9 +1121,50 @@ const AssistantMessageBody = React.memo(({
     const createSessionFromAssistantMessage = useSessionUIStore((state) => state.createSessionFromAssistantMessage);
     const currentSessionId = useSessionUIStore((state) => state.currentSessionId);
     const getDirectoryForSession = useSessionUIStore((state) => state.getDirectoryForSession);
+    const currentSession = useGlobalSessionsStore((state) => {
+        if (!sessionId) return null;
+        for (const candidate of state.activeSessions) {
+            if (candidate.id === sessionId) return candidate;
+        }
+        for (const candidate of state.archivedSessions) {
+            if (candidate.id === sessionId) return candidate;
+        }
+        return null;
+    });
     const openMultiRunLauncherWithPrompt = useUIStore((state) => state.openMultiRunLauncherWithPrompt);
     const projects = useProjectsStore((state) => state.projects);
     const effectiveDirectory = useEffectiveDirectory();
+    const currentReviewTransferDirection = getReviewTransferDirection(currentSession);
+    const isReviewSessionView = currentReviewTransferDirection === 'review-to-original';
+    const reviewTransferDirection = (!isMobile && !isVSCode) ? currentReviewTransferDirection : null;
+    const reviewTransferAction = React.useMemo(() => {
+        const transferText = assistantPlanText.trim();
+        if (!sessionId || !effectiveDirectory || !transferText || !reviewTransferDirection) return undefined;
+        if (reviewTransferDirection === 'review-to-original') {
+            return {
+                ariaLabel: t('chat.messageBody.actions.sendReviewFeedback'),
+                tooltip: t('chat.messageBody.actions.sendReviewFeedback'),
+                onClick: async () => {
+                    try {
+                        await sendReviewFeedbackToOriginal(sessionId, effectiveDirectory, transferText);
+                    } catch (error) {
+                        console.error('[review-flow] failed to send review feedback', error);
+                    }
+                },
+            };
+        }
+        return {
+            ariaLabel: t('chat.messageBody.actions.sendImplementationResponse'),
+            tooltip: t('chat.messageBody.actions.sendImplementationResponse'),
+            onClick: async () => {
+                try {
+                    await sendImplementationResponseToReviewer(sessionId, effectiveDirectory, transferText);
+                } catch (error) {
+                    console.error('[review-flow] failed to send implementation response', error);
+                }
+            },
+        };
+    }, [assistantPlanText, effectiveDirectory, reviewTransferDirection, sessionId, t]);
     const [isPlanDialogOpen, setIsPlanDialogOpen] = React.useState(false);
     const [isSavingPlan, setIsSavingPlan] = React.useState(false);
     const [isForkDialogOpen, setIsForkDialogOpen] = React.useState(false);
@@ -1481,8 +1578,9 @@ const AssistantMessageBody = React.memo(({
             onCopyMessage={onCopyMessage}
             onShareImage={shareMessageAsImage}
             ttsText={assistantPlanText}
+            reviewTransferAction={reviewTransferAction}
         />
-    ), [assistantPlanText, hasCopyableText, isTouchContext, onCopyMessage, shareMessageAsImage]);
+    ), [assistantPlanText, hasCopyableText, isTouchContext, onCopyMessage, reviewTransferAction, shareMessageAsImage]);
 
     const renderJustificationActions = React.useCallback((activity: NonNullable<TurnGroupingContext['activityParts']>[number]) => {
         if (!showSplitAssistantMessageActions || !isSortedRenderMode) {
@@ -1830,7 +1928,7 @@ const AssistantMessageBody = React.memo(({
                     <TooltipContent sideOffset={6}>{t('chat.messageBody.actions.openPreview')}</TooltipContent>
                 </Tooltip>
             ) : null}
-            {canUseProjectPlanActions ? (
+            {canUseProjectPlanActions && !isReviewSessionView ? (
                 <Tooltip>
                     <TooltipTrigger asChild>
                         <Button
@@ -1851,7 +1949,7 @@ const AssistantMessageBody = React.memo(({
                     <TooltipContent sideOffset={6}>{t('chat.messageBody.actions.saveAsPlan')}</TooltipContent>
                 </Tooltip>
             ) : null}
-            {!isMiniChatSurface ? <Tooltip>
+            {!isMiniChatSurface && !isReviewSessionView ? <Tooltip>
                 <TooltipTrigger asChild>
                     <Button
                         type="button"
@@ -1866,7 +1964,7 @@ const AssistantMessageBody = React.memo(({
                 </TooltipTrigger>
                 <TooltipContent sideOffset={6}>{t('chat.messageBody.actions.startNewSession')}</TooltipContent>
             </Tooltip> : null}
-            {canShowMultiRunAction ? (
+            {canShowMultiRunAction && !isReviewSessionView ? (
                 <Tooltip>
                     <TooltipTrigger asChild>
                         <Button
diff --git a/packages/ui/src/lib/i18n/messages/en.ts b/packages/ui/src/lib/i18n/messages/en.ts
index 4e9a8ce6..72dc65c8 100644
--- a/packages/ui/src/lib/i18n/messages/en.ts
+++ b/packages/ui/src/lib/i18n/messages/en.ts
@@ -1641,6 +1641,7 @@ export const dict = {
   'chat.commandAutocomplete.command.compactDescription': 'Compress session history using AI to reduce context size',
   'chat.commandAutocomplete.command.summaryDescription': 'Non-destructive session summary. Optional topic hint after the command.',
   'chat.commandAutocomplete.command.workspaceReviewDescription': 'Review the workspace diff for intent, correctness, and adequacy, graded by severity.',
+  'chat.commandAutocomplete.command.handoffReviewDescription': 'Create or reuse a separate review session from a generated handoff.',
   'chat.commandAutocomplete.command.featurePlanDescription': 'Start a guided, back-and-forth planning session for a new feature.',
   'chat.commandAutocomplete.command.catchUpDescription': 'Re-establish context: what you were doing and where to pick up.',
   'chat.commandAutocomplete.command.debugDescription': 'Guided root-cause investigation for a bug before proposing a fix.',
@@ -1767,6 +1768,8 @@ export const dict = {
   'snippets.source.project': 'project',
   'chat.chatInput.toast.compactFailed': 'Failed to compact session',
   'chat.chatInput.toast.summaryFailed': 'Failed to generate summary',
+  'chat.messageBody.actions.sendReviewFeedback': 'Send review feedback to implementing agent',
+  'chat.messageBody.actions.sendImplementationResponse': 'Send implementation response to reviewing agent',
   'chat.chatInput.toast.reviewFailed': 'Failed to review changes',
   'chat.chatInput.toast.planFeatureFailed': 'Failed to start feature planning',
   'chat.chatInput.toast.catchUpFailed': 'Failed to catch up',
diff --git a/packages/ui/src/lib/i18n/messages/es.ts b/packages/ui/src/lib/i18n/messages/es.ts
index 56e46246..a6c56cd0 100644
--- a/packages/ui/src/lib/i18n/messages/es.ts
+++ b/packages/ui/src/lib/i18n/messages/es.ts
@@ -1607,6 +1607,7 @@ export const dict: Record<I18nKey, string> = {
   "chat.commandAutocomplete.command.compactDescription": "Comprimir el historial de la sesión usando IA para reducir el tamaño del contexto",
   "chat.commandAutocomplete.command.summaryDescription": "Resumen no destructivo de la sesión. Pista opcional del tema después del comando.",
   "chat.commandAutocomplete.command.workspaceReviewDescription": "Revisa el diff del espacio de trabajo en intención, corrección y adecuación, con hallazgos por severidad.",
+  "chat.commandAutocomplete.command.handoffReviewDescription": "Crea o reutiliza una sesión de revisión separada a partir de un handoff generado.",
   "chat.commandAutocomplete.command.featurePlanDescription": "Inicia una sesión de planificación guiada e interactiva para una nueva función.",
   "chat.commandAutocomplete.command.catchUpDescription": "Recupera el contexto: qué estabas haciendo y por dónde continuar.",
   "chat.commandAutocomplete.command.debugDescription": "Investigación guiada de la causa raíz de un error antes de proponer una solución.",
@@ -1733,6 +1734,8 @@ export const dict: Record<I18nKey, string> = {
   "snippets.source.project": "proyecto",
   "chat.chatInput.toast.compactFailed": "No se pudo comprimir la sesión",
   "chat.chatInput.toast.summaryFailed": "No se pudo generar el resumen",
+  "chat.messageBody.actions.sendReviewFeedback": "Enviar feedback de revisión al agente que implementa los cambios",
+  "chat.messageBody.actions.sendImplementationResponse": "Enviar respuesta de implementación al agente revisor",
   "chat.chatInput.toast.reviewFailed": "No se pudieron revisar los cambios",
   "chat.chatInput.toast.planFeatureFailed": "No se pudo iniciar la planificación de la función",
   "chat.chatInput.toast.catchUpFailed": "No se pudo recuperar el contexto",
diff --git a/packages/ui/src/lib/i18n/messages/ko.ts b/packages/ui/src/lib/i18n/messages/ko.ts
index 345b1631..d493755b 100644
--- a/packages/ui/src/lib/i18n/messages/ko.ts
+++ b/packages/ui/src/lib/i18n/messages/ko.ts
@@ -1643,6 +1643,7 @@ export const dict: Record<I18nKey, string> = {
   'chat.commandAutocomplete.command.compactDescription': 'AI로 세션 기록을 압축해 컨텍스트 크기를 줄입니다',
   'chat.commandAutocomplete.command.summaryDescription': '세션 기록을 안전하게 요약합니다. 명령 뒤에 선택적으로 주제 힌트를 넣을 수 있습니다.',
   'chat.commandAutocomplete.command.workspaceReviewDescription': '워크스페이스 diff의 의도, 정확성, 적절성을 검토하고 심각도별로 분류합니다.',
+  'chat.commandAutocomplete.command.handoffReviewDescription': '생성된 인수인계로 별도의 리뷰 세션을 만들거나 재사용합니다.',
   'chat.commandAutocomplete.command.featurePlanDescription': '새 기능을 위한 대화형 가이드 계획 세션을 시작합니다.',
   'chat.commandAutocomplete.command.catchUpDescription': '맥락을 다시 파악합니다: 무엇을 하고 있었고 어디서 이어서 할지.',
   'chat.commandAutocomplete.command.debugDescription': '수정안을 제시하기 전에 버그의 근본 원인을 단계적으로 조사합니다.',
@@ -1767,6 +1768,8 @@ export const dict: Record<I18nKey, string> = {
   'snippets.source.project': '프로젝트',
   'chat.chatInput.toast.compactFailed': '세션 압축 실패',
   'chat.chatInput.toast.summaryFailed': '요약 생성 실패',
+  'chat.messageBody.actions.sendReviewFeedback': '리뷰 피드백을 변경 구현 에이전트에게 보내기',
+  'chat.messageBody.actions.sendImplementationResponse': '구현 응답을 리뷰 에이전트에게 보내기',
   'chat.chatInput.toast.reviewFailed': '변경사항 검토 실패',
   'chat.chatInput.toast.planFeatureFailed': '기능 계획을 시작하지 못했습니다',
   'chat.chatInput.toast.catchUpFailed': '컨텍스트를 불러오지 못했습니다',
diff --git a/packages/ui/src/lib/i18n/messages/pl.ts b/packages/ui/src/lib/i18n/messages/pl.ts
index 68430a76..7df3fb3c 100644
--- a/packages/ui/src/lib/i18n/messages/pl.ts
+++ b/packages/ui/src/lib/i18n/messages/pl.ts
@@ -622,6 +622,7 @@ export const dict: Record<I18nKey, string> = {
   'chat.commandAutocomplete.command.compactDescription': 'Skompresuj historię sesji używając AI aby zredukować rozmiar kontekstu',
   'chat.commandAutocomplete.command.summaryDescription': 'Niedestrukcyjne podsumowanie sesji. Opcjonalna wskazówka tematu po poleceniu.',
   'chat.commandAutocomplete.command.workspaceReviewDescription': 'Sprawdź diff obszaru roboczego pod kątem zamiaru, poprawności i adekwatności — ze znaleziskami według wagi.',
+  'chat.commandAutocomplete.command.handoffReviewDescription': 'Utwórz lub użyj ponownie osobnej sesji przeglądu z wygenerowanego handoffu.',
   'chat.commandAutocomplete.command.featurePlanDescription': 'Rozpocznij prowadzoną, interaktywną sesję planowania nowej funkcji.',
   'chat.commandAutocomplete.command.catchUpDescription': 'Przywróć kontekst: nad czym pracowałeś i od czego kontynuować.',
   'chat.commandAutocomplete.command.debugDescription': 'Prowadzone badanie pierwotnej przyczyny błędu przed zaproponowaniem poprawki.',
@@ -1052,6 +1053,8 @@ export const dict: Record<I18nKey, string> = {
   'chat.chatInput.toast.sendAttachmentsFailed': 'Nie udało się wysłać załączników. Spróbuj użyć mniejszej liczby plików lub mniejszych obrazów.',
   'chat.chatInput.toast.someFilesSkipped': 'Pominięto niektóre pliki:\n{summary}',
   'chat.chatInput.toast.summaryFailed': 'Nie udało się wygenerować podsumowania',
+  'chat.messageBody.actions.sendReviewFeedback': 'Wyślij uwagi z przeglądu do agenta wdrażającego zmiany',
+  'chat.messageBody.actions.sendImplementationResponse': 'Wyślij odpowiedź wdrożeniową do agenta przeglądającego',
   'chat.chatInput.toast.togglePermissionAutoAcceptFailed': 'Nie udało się przełączyć automatycznej akceptacji uprawnień',
   'chat.chatInput.toast.vscodePickFailed': 'Nie udało się wybrać plików w VS Code',
   'chat.chatInput.worktreeNew': '+ Nowe',
diff --git a/packages/ui/src/lib/i18n/messages/pt-BR.ts b/packages/ui/src/lib/i18n/messages/pt-BR.ts
index a0e4f870..17eb05c7 100644
--- a/packages/ui/src/lib/i18n/messages/pt-BR.ts
+++ b/packages/ui/src/lib/i18n/messages/pt-BR.ts
@@ -1607,6 +1607,7 @@ export const dict: Record<I18nKey, string> = {
   "chat.commandAutocomplete.command.compactDescription": "Comprimir o histórico da sessão usando IA para reduzir o tamanho do contexto",
   "chat.commandAutocomplete.command.summaryDescription": "Resumo não destrutivo da sessão. Dica opcional do tema após o comando.",
   "chat.commandAutocomplete.command.workspaceReviewDescription": "Revisa o diff do workspace quanto a intenção, correção e adequação, com achados por severidade.",
+  "chat.commandAutocomplete.command.handoffReviewDescription": "Crie ou reutilize uma sessão separada de revisão a partir de um handoff gerado.",
   "chat.commandAutocomplete.command.featurePlanDescription": "Inicie uma sessão de planejamento guiada e interativa para uma nova funcionalidade.",
   "chat.commandAutocomplete.command.catchUpDescription": "Retome o contexto: o que você estava fazendo e por onde continuar.",
   "chat.commandAutocomplete.command.debugDescription": "Investigação guiada da causa raiz de um bug antes de propor uma correção.",
@@ -1733,6 +1734,8 @@ export const dict: Record<I18nKey, string> = {
   "snippets.source.project": "projeto",
   "chat.chatInput.toast.compactFailed": "Não foi possível comprimir a sessão",
   "chat.chatInput.toast.summaryFailed": "Não foi possível gerar o resumo",
+  "chat.messageBody.actions.sendReviewFeedback": "Enviar feedback da revisão ao agente que implementa as mudanças",
+  "chat.messageBody.actions.sendImplementationResponse": "Enviar resposta da implementação ao agente revisor",
   "chat.chatInput.toast.reviewFailed": "Não foi possível revisar as alterações",
   "chat.chatInput.toast.planFeatureFailed": "Não foi possível iniciar o planejamento da funcionalidade",
   "chat.chatInput.toast.catchUpFailed": "Não foi possível retomar o contexto",
diff --git a/packages/ui/src/lib/i18n/messages/uk.ts b/packages/ui/src/lib/i18n/messages/uk.ts
index 522d8306..72fffaa1 100644
--- a/packages/ui/src/lib/i18n/messages/uk.ts
+++ b/packages/ui/src/lib/i18n/messages/uk.ts
@@ -1607,6 +1607,7 @@ export const dict: Record<I18nKey, string> = {
   "chat.commandAutocomplete.command.compactDescription": "Стиснути історію сесії за допомогою ШІ, щоб зменшити розмір контексту",
   "chat.commandAutocomplete.command.summaryDescription": "Неруйнівний підсумок сесії. Після команди можна додати тему.",
   "chat.commandAutocomplete.command.workspaceReviewDescription": "Перевірити diff робочого простору на намір, коректність і адекватність — зі знахідками за рівнем критичності.",
+  "chat.commandAutocomplete.command.handoffReviewDescription": "Створити або повторно використати окрему сесію ревʼю зі згенерованого handoff.",
   "chat.commandAutocomplete.command.featurePlanDescription": "Розпочати покрокову діалогову сесію планування нової фічі.",
   "chat.commandAutocomplete.command.catchUpDescription": "Повернутись у контекст: над чим працювали і звідки продовжити.",
   "chat.commandAutocomplete.command.debugDescription": "Кероване дослідження першопричини бага перед тим, як пропонувати фікс.",
@@ -1733,6 +1734,8 @@ export const dict: Record<I18nKey, string> = {
   "snippets.source.project": "проєкт",
   "chat.chatInput.toast.compactFailed": "Не вдалося стиснути сесію",
   "chat.chatInput.toast.summaryFailed": "Не вдалося створити підсумок",
+  "chat.messageBody.actions.sendReviewFeedback": "Надіслати фідбек ревʼю агенту, який реалізує зміни",
+  "chat.messageBody.actions.sendImplementationResponse": "Надіслати відповідь щодо реалізації агенту-ревʼюеру",
   "chat.chatInput.toast.reviewFailed": "Не вдалося переглянути зміни",
   "chat.chatInput.toast.planFeatureFailed": "Не вдалося розпочати планування фічі",
   "chat.chatInput.toast.catchUpFailed": "Не вдалося зібрати контекст",
diff --git a/packages/ui/src/lib/i18n/messages/zh-CN.ts b/packages/ui/src/lib/i18n/messages/zh-CN.ts
index 89b95199..d561e987 100644
--- a/packages/ui/src/lib/i18n/messages/zh-CN.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-CN.ts
@@ -1607,6 +1607,7 @@ export const dict: Record<I18nKey, string> = {
   'chat.commandAutocomplete.command.compactDescription': '使用 AI 压缩会话历史以减少上下文大小',
   'chat.commandAutocomplete.command.summaryDescription': '非破坏性会话总结。命令后可选填主题提示。',
   'chat.commandAutocomplete.command.workspaceReviewDescription': '审查工作区 diff 的意图、正确性与充分性，并按严重程度分级。',
+  'chat.commandAutocomplete.command.handoffReviewDescription': '根据生成的交接内容创建或复用独立的审查会话。',
   'chat.commandAutocomplete.command.featurePlanDescription': '为新功能开始一次引导式的来回规划会话。',
   'chat.commandAutocomplete.command.catchUpDescription': '重新进入上下文：你之前在做什么、从哪里继续。',
   'chat.commandAutocomplete.command.debugDescription': '在提出修复方案前，引导式地排查 bug 的根本原因。',
@@ -1733,6 +1734,8 @@ export const dict: Record<I18nKey, string> = {
   'snippets.source.project': '项目',
   'chat.chatInput.toast.compactFailed': '压缩会话失败',
   'chat.chatInput.toast.summaryFailed': '生成总结失败',
+  'chat.messageBody.actions.sendReviewFeedback': '将审查反馈发送给实现更改的代理',
+  'chat.messageBody.actions.sendImplementationResponse': '将实现回应发送给审查代理',
   'chat.chatInput.toast.reviewFailed': '审查变更失败',
   'chat.chatInput.toast.planFeatureFailed': '无法开始功能规划',
   'chat.chatInput.toast.catchUpFailed': '无法获取上下文',
diff --git a/packages/ui/src/lib/i18n/messages/zh-TW.ts b/packages/ui/src/lib/i18n/messages/zh-TW.ts
index 9c86ed54..ecc1171d 100644
--- a/packages/ui/src/lib/i18n/messages/zh-TW.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-TW.ts
@@ -1611,6 +1611,7 @@ export const dict: Record<I18nKey, string> = {
   'chat.commandAutocomplete.command.compactDescription': '使用 AI 壓縮會話歷史以減少上下文大小',
   'chat.commandAutocomplete.command.summaryDescription': '非破壞性會話總結。命令後可選填主題提示。',
   'chat.commandAutocomplete.command.workspaceReviewDescription': '審查工作區 diff 的意圖、正確性與充分性，並依嚴重程度分級。',
+  'chat.commandAutocomplete.command.handoffReviewDescription': '根據生成的交接內容建立或重用獨立的審查會話。',
   'chat.commandAutocomplete.command.featurePlanDescription': '為新功能開始一次引導式的來回規劃工作階段。',
   'chat.commandAutocomplete.command.catchUpDescription': '重新進入上下文：你之前在做什麼、從哪裡繼續。',
   'chat.commandAutocomplete.command.debugDescription': '在提出修復方案前，引導式地排查 bug 的根本原因。',
@@ -1737,6 +1738,8 @@ export const dict: Record<I18nKey, string> = {
   'snippets.source.project': '項目',
   'chat.chatInput.toast.compactFailed': '壓縮會話失敗',
   'chat.chatInput.toast.summaryFailed': '生成總結失敗',
+  'chat.messageBody.actions.sendReviewFeedback': '將審查回饋傳送給實作變更的代理',
+  'chat.messageBody.actions.sendImplementationResponse': '將實作回應傳送給審查代理',
   'chat.chatInput.toast.reviewFailed': '審查變更失敗',
   'chat.chatInput.toast.planFeatureFailed': '無法開始功能規劃',
   'chat.chatInput.toast.catchUpFailed': '無法取得上下文',
diff --git a/packages/ui/src/lib/magicPrompts.ts b/packages/ui/src/lib/magicPrompts.ts
index 7dd670d2..f8adeb37 100644
--- a/packages/ui/src/lib/magicPrompts.ts
+++ b/packages/ui/src/lib/magicPrompts.ts
@@ -29,6 +29,11 @@ export type MagicPromptId =
   | 'session.summary.instructions'
   | 'session.review.visible'
   | 'session.review.instructions'
+  | 'session.reviewHandoff.visible'
+  | 'session.reviewHandoff.instructions'
+  | 'session.reviewSession.visible'
+  | 'session.reviewFeedbackToImplementer.visible'
+  | 'session.implementationResponseToReviewer.visible'
   | 'session.plan.visible'
   | 'session.plan.instructions'
   | 'session.catchup.visible'
@@ -603,6 +608,76 @@ Output:
 - If you find nothing real, say so plainly instead of inventing findings.
 
 Keep the review concise and practical. Respond in the same language the user uses.`,
+  },
+  {
+    id: 'session.reviewHandoff.visible',
+    title: 'Review Handoff Visible Prompt',
+    group: 'Session',
+    description: 'Visible user message sent by the /handoff-review command.',
+    template: 'Prepare a handoff for another agent to review this work.',
+  },
+  {
+    id: 'session.reviewHandoff.instructions',
+    title: 'Review Handoff Instructions',
+    group: 'Session',
+    description: 'Hidden instructions attached to the /handoff-review command. Produces a handoff for a separate review agent.',
+    template: `Produce a review handoff for another agent. Do not compact or mutate session history. Your output is an assistant message that OpenChamber will send to a separate reviewer agent.
+
+Include:
+- The user's original intent and any later clarifications that changed the intent
+- What was implemented and why
+- Files changed, with brief purpose per file
+- Important design decisions and tradeoffs
+- Validation/tests run, if known
+- Known gaps, uncertainty, or areas the reviewer should inspect closely
+
+Formatting:
+- Concise markdown with clear sections
+- No preamble like "Here is a handoff"
+- Do not mention OpenChamber metadata, linked sessions, session IDs, or routing
+- Respond in the same language the user used most in the conversation`,
+  },
+  {
+    id: 'session.reviewSession.visible',
+    title: 'Review Session Starter Prompt',
+    group: 'Session',
+    description: 'Visible user message sent to the generated review session.',
+    placeholders: [
+      { key: 'handoff', description: 'The generated implementation handoff.' },
+    ],
+    template: `Please review the changes described in this handoff.
+
+Focus on correctness, regressions, missing implementation, missing tests, and whether the implementation satisfies the stated intent. Provide concise, actionable feedback for the agent implementing the changes.
+
+{{handoff}}`,
+  },
+  {
+    id: 'session.reviewFeedbackToImplementer.visible',
+    title: 'Review Feedback Transfer Prompt',
+    group: 'Session',
+    description: 'Visible user message sent from a review session back to the implementing agent.',
+    placeholders: [
+      { key: 'review_feedback', description: 'Reviewer assistant feedback text.' },
+    ],
+    template: `Another agent reviewed your changes and left the feedback below.
+
+Please review the feedback, resolve the relevant issues, and explain what you changed.
+
+{{review_feedback}}`,
+  },
+  {
+    id: 'session.implementationResponseToReviewer.visible',
+    title: 'Implementation Response Transfer Prompt',
+    group: 'Session',
+    description: 'Visible user message sent from the implementing agent back to the review session.',
+    placeholders: [
+      { key: 'implementation_response', description: 'Implementing assistant response text.' },
+    ],
+    template: `The agent implementing the changes has responded to the previous review feedback.
+
+Please review the latest state again and report any remaining issues.
+
+{{implementation_response}}`,
   },
   {
     id: 'session.plan.visible',
diff --git a/packages/ui/src/lib/opencode/client.ts b/packages/ui/src/lib/opencode/client.ts
index ee83a075..285355dc 100644
--- a/packages/ui/src/lib/opencode/client.ts
+++ b/packages/ui/src/lib/opencode/client.ts
@@ -486,20 +486,22 @@ class OpencodeService {
     return Array.isArray(response.data) ? response.data : [];
   }
 
-  async createSession(params?: { parentID?: string; title?: string }, directory?: string | null): Promise<Session> {
+  async createSession(params?: { parentID?: string; title?: string; metadata?: Record<string, unknown> }, directory?: string | null): Promise<Session> {
     const requestDirectory = this.normalizeCandidatePath(directory) ?? this.currentDirectory;
     const response = await this.client.session.create({
       ...(requestDirectory ? { directory: requestDirectory } : {}),
       parentID: params?.parentID,
       title: params?.title,
+      metadata: params?.metadata,
     });
     return unwrapSdkData(response, 'session.create');
   }
 
-  async getSession(id: string): Promise<Session> {
+  async getSession(id: string, directory?: string | null): Promise<Session> {
+    const requestDirectory = this.normalizeCandidatePath(directory) ?? this.currentDirectory;
     const response = await this.client.session.get({
       sessionID: id,
-      ...(this.currentDirectory ? { directory: this.currentDirectory } : {})
+      ...(requestDirectory ? { directory: requestDirectory } : {})
     });
     return unwrapSdkData(response, 'session.get');
   }
@@ -515,12 +517,13 @@ class OpencodeService {
 
   async updateSession(
     id: string,
-    patch: { title?: string; time?: { archived?: number | null } },
+    patch: { title?: string; metadata?: Record<string, unknown>; time?: { archived?: number | null } },
     directory?: string | null,
   ): Promise<Session> {
     const requestDirectory = this.normalizeCandidatePath(directory) ?? this.currentDirectory;
     const sdkPatch = {
       ...(patch.title !== undefined ? { title: patch.title } : {}),
+      ...(patch.metadata !== undefined ? { metadata: patch.metadata } : {}),
       ...(patch.time?.archived !== undefined && patch.time.archived !== null ? { time: { archived: patch.time.archived } } : {}),
     };
     const response = await this.client.session.update({
diff --git a/packages/ui/src/lib/reviewFlow.ts b/packages/ui/src/lib/reviewFlow.ts
new file mode 100644
index 00000000..de51f47e
--- /dev/null
+++ b/packages/ui/src/lib/reviewFlow.ts
@@ -0,0 +1,235 @@
+import type { Message, Session } from '@opencode-ai/sdk/v2/client';
+import { opencodeClient } from '@/lib/opencode/client';
+import { renderMagicPrompt } from '@/lib/magicPrompts';
+import { flattenAssistantTextParts } from '@/lib/messages/messageText';
+import {
+  getOriginalSessionID,
+  getReviewSessionID,
+  getSessionMetadata,
+  isReviewSession,
+  withoutReviewSessionLink,
+  withReviewSessionLink,
+  withReviewSessionMarker,
+} from '@/lib/sessionReviewMetadata';
+import { useConfigStore } from '@/stores/useConfigStore';
+import { useContextStore } from '@/stores/contextStore';
+import { useGlobalSessionsStore } from '@/stores/useGlobalSessionsStore';
+import { useUIStore } from '@/stores/useUIStore';
+import { optimisticSend, patchSessionMetadata, waitForConnectionOrThrow } from '@/sync/session-actions';
+import { getSyncMessages, getSyncParts, registerSessionDirectory } from '@/sync/sync-refs';
+import { markPendingUserSendAnimation } from '@/lib/userSendAnimation';
+
+const HANDOFF_TIMEOUT_MS = 180_000;
+const HANDOFF_POLL_MS = 400;
+const REVIEW_SESSION_TITLE = 'Review of workspace changes';
+
+type SessionModelContext = {
+  providerID: string;
+  modelID: string;
+  agent?: string;
+  variant?: string;
+};
+
+type StartReviewFlowInput = SessionModelContext & {
+  originalSessionID: string;
+  directory: string;
+  agentMentionName?: string;
+};
+
+const isMessageCompleted = (message: Message): boolean => {
+  const finish = (message as { finish?: unknown }).finish;
+  if (typeof finish === 'string' && finish.length > 0) return true;
+  const completed = (message as { time?: { completed?: unknown } }).time?.completed;
+  return typeof completed === 'number' && completed > 0;
+};
+
+const getMessageCreatedAt = (message: Message): number => {
+  const created = (message as { time?: { created?: unknown } }).time?.created;
+  return typeof created === 'number' && Number.isFinite(created) ? created : 0;
+};
+
+const getMessageRole = (message: Message): string => {
+  const role = (message as { role?: unknown }).role;
+  return typeof role === 'string' ? role : '';
+};
+
+const waitForAssistantText = async (sessionID: string, directory: string, afterCreatedAt: number): Promise<string> => {
+  const deadline = Date.now() + HANDOFF_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const messages = getSyncMessages(sessionID, directory);
+    const candidates = messages
+      .filter((message) => getMessageRole(message) === 'assistant')
+      .filter((message) => getMessageCreatedAt(message) >= afterCreatedAt - 1000)
+      .filter(isMessageCompleted)
+      .sort((left, right) => getMessageCreatedAt(right) - getMessageCreatedAt(left));
+
+    for (const message of candidates) {
+      const text = flattenAssistantTextParts(getSyncParts(message.id, directory)).trim();
+      if (text) return text;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, HANDOFF_POLL_MS));
+  }
+  throw new Error('Timed out waiting for handoff response');
+};
+
+const resolveModelContext = (sessionID: string): SessionModelContext | null => {
+  const context = useContextStore.getState();
+  const config = useConfigStore.getState();
+  const agent = context.getSessionAgentSelection(sessionID) || config.currentAgentName || undefined;
+  const sessionModel = context.getSessionModelSelection(sessionID);
+  const agentModel = agent ? context.getAgentModelForSession(sessionID, agent) : null;
+  const selectedModel = agentModel || sessionModel || (config.currentProviderId && config.currentModelId
+    ? { providerId: config.currentProviderId, modelId: config.currentModelId }
+    : null);
+  if (!selectedModel?.providerId || !selectedModel?.modelId) return null;
+  const variant = agent
+    ? context.getAgentModelVariantForSession(sessionID, agent, selectedModel.providerId, selectedModel.modelId) || config.currentVariant || undefined
+    : config.currentVariant || undefined;
+  return {
+    providerID: selectedModel.providerId,
+    modelID: selectedModel.modelId,
+    agent,
+    variant,
+  };
+};
+
+const sendPlainMessage = async (
+  sessionID: string,
+  directory: string,
+  text: string,
+  modelContext?: SessionModelContext | null,
+  additionalParts?: Array<{ text: string; synthetic?: boolean }>,
+): Promise<void> => {
+  const resolved = modelContext ?? resolveModelContext(sessionID);
+  if (!resolved) throw new Error('Select a model before sending review flow messages');
+  markPendingUserSendAnimation(sessionID);
+  await optimisticSend({
+    sessionId: sessionID,
+    content: text,
+    directory,
+    providerID: resolved.providerID,
+    modelID: resolved.modelID,
+    agent: resolved.agent,
+    onOptimisticInsert: () => requestChatForceScrollBottom(sessionID),
+    send: (messageID) => opencodeClient.sendMessage({
+      id: sessionID,
+      directory,
+      providerID: resolved.providerID,
+      modelID: resolved.modelID,
+      agent: resolved.agent,
+      variant: resolved.variant,
+      text,
+      additionalParts,
+      messageId: messageID,
+    }).then(() => undefined),
+  });
+};
+
+const requestChatForceScrollBottom = (sessionId: string): void => {
+  if (typeof window === 'undefined') return;
+  window.dispatchEvent(new CustomEvent('openchamber:chat-force-scroll-bottom', {
+    detail: { sessionId },
+  }));
+};
+
+const openReviewSessionPanel = (directory: string, session: Session): void => {
+  useUIStore.getState().openContextPanelTab(directory, {
+    mode: 'chat',
+    dedupeKey: `session:${session.id}`,
+    label: session.title ?? null,
+  });
+};
+
+const getSessionOrNull = async (sessionID: string, directory: string): Promise<Session | null> => {
+  try {
+    return await opencodeClient.getSession(sessionID, directory);
+  } catch {
+    return null;
+  }
+};
+
+const createOrReuseReviewSession = async (originalSessionID: string, directory: string): Promise<Session> => {
+  const original = await opencodeClient.getSession(originalSessionID, directory);
+  const existingReviewID = getReviewSessionID(original);
+  if (existingReviewID) {
+    const existing = await getSessionOrNull(existingReviewID, directory);
+    if (existing && isReviewSession(existing)) return existing;
+    await patchSessionMetadata(originalSessionID, directory, (metadata) => {
+      const next = { ...metadata };
+      const openchamber = next.openchamber;
+      if (openchamber && typeof openchamber === 'object' && !Array.isArray(openchamber)) {
+        const rest = { ...(openchamber as Record<string, unknown>) };
+        delete rest.reviewSessionID;
+        next.openchamber = rest;
+      }
+      return next;
+    });
+  }
+
+  const review = await opencodeClient.createSession({
+    title: REVIEW_SESSION_TITLE,
+    metadata: withReviewSessionMarker({}, originalSessionID),
+  }, directory);
+  registerSessionDirectory(review.id, directory);
+  try {
+    await patchSessionMetadata(originalSessionID, directory, (metadata) => withReviewSessionLink(metadata, review.id));
+  } catch (error) {
+    await opencodeClient.deleteSession(review.id, directory).catch((deleteError) => {
+      console.warn('[review-flow] failed to delete unlinked review session after link failure', deleteError);
+    });
+    throw error;
+  }
+  useGlobalSessionsStore.getState().upsertSession(review);
+  return review;
+};
+
+export const startReviewFlow = async (input: StartReviewFlowInput): Promise<void> => {
+  await waitForConnectionOrThrow();
+  const visibleText = await renderMagicPrompt('session.reviewHandoff.visible');
+  const instructionsText = await renderMagicPrompt('session.reviewHandoff.instructions');
+  const startedAt = Date.now();
+  await sendPlainMessage(input.originalSessionID, input.directory, visibleText, input, [
+    { text: instructionsText, synthetic: true },
+  ]);
+  const handoff = await waitForAssistantText(input.originalSessionID, input.directory, startedAt);
+  const reviewSession = await createOrReuseReviewSession(input.originalSessionID, input.directory);
+  const reviewPrompt = await renderMagicPrompt('session.reviewSession.visible', { handoff });
+  await sendPlainMessage(reviewSession.id, input.directory, reviewPrompt, {
+    providerID: input.providerID,
+    modelID: input.modelID,
+  });
+  openReviewSessionPanel(input.directory, reviewSession);
+};
+
+export const sendReviewFeedbackToOriginal = async (reviewSessionID: string, directory: string, reviewFeedback: string): Promise<void> => {
+  const reviewSession = await opencodeClient.getSession(reviewSessionID, directory);
+  const originalSessionID = getOriginalSessionID(reviewSession);
+  if (!originalSessionID) throw new Error('Original session is missing');
+  const prompt = await renderMagicPrompt('session.reviewFeedbackToImplementer.visible', { review_feedback: reviewFeedback });
+  await sendPlainMessage(originalSessionID, directory, prompt);
+};
+
+export const sendImplementationResponseToReviewer = async (originalSessionID: string, directory: string, implementationResponse: string): Promise<void> => {
+  const originalSession = await opencodeClient.getSession(originalSessionID, directory);
+  const reviewSessionID = getReviewSessionID(originalSession);
+  if (!reviewSessionID) throw new Error('Review session is missing');
+  let reviewSession: Session;
+  try {
+    reviewSession = await opencodeClient.getSession(reviewSessionID, directory);
+  } catch (error) {
+    await patchSessionMetadata(originalSessionID, directory, (metadata) => withoutReviewSessionLink(metadata, reviewSessionID));
+    throw error;
+  }
+  const prompt = await renderMagicPrompt('session.implementationResponseToReviewer.visible', { implementation_response: implementationResponse });
+  await sendPlainMessage(reviewSessionID, directory, prompt);
+  openReviewSessionPanel(directory, reviewSession);
+};
+
+export const getReviewTransferDirection = (session: Session | null | undefined): 'review-to-original' | 'original-to-review' | null => {
+  if (isReviewSession(session)) return 'review-to-original';
+  if (getReviewSessionID(session)) return 'original-to-review';
+  return null;
+};
+
+export const readSessionReviewMetadata = (session: Session | null | undefined) => getSessionMetadata(session);
diff --git a/packages/ui/src/lib/sessionReviewMetadata.ts b/packages/ui/src/lib/sessionReviewMetadata.ts
new file mode 100644
index 00000000..6ab9de30
--- /dev/null
+++ b/packages/ui/src/lib/sessionReviewMetadata.ts
@@ -0,0 +1,82 @@
+import type { Session } from '@opencode-ai/sdk/v2';
+
+export type SessionMetadataRecord = Record<string, unknown>;
+
+type OpenChamberMetadata = {
+  kind?: 'review';
+  originalSessionID?: string;
+  reviewSessionID?: string;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value && typeof value === 'object' && !Array.isArray(value));
+
+export const getSessionMetadata = (session: Session | null | undefined): SessionMetadataRecord => {
+  const metadata = (session as (Session & { metadata?: unknown }) | null | undefined)?.metadata;
+  return isRecord(metadata) ? metadata : {};
+};
+
+const getOpenChamberMetadata = (metadata: SessionMetadataRecord): OpenChamberMetadata => {
+  const value = metadata.openchamber;
+  return isRecord(value) ? value as OpenChamberMetadata : {};
+};
+
+export const getReviewSessionID = (session: Session | null | undefined): string | null => {
+  const value = getOpenChamberMetadata(getSessionMetadata(session)).reviewSessionID;
+  return typeof value === 'string' && value.trim().length > 0 ? value : null;
+};
+
+export const getOriginalSessionID = (session: Session | null | undefined): string | null => {
+  const value = getOpenChamberMetadata(getSessionMetadata(session)).originalSessionID;
+  return typeof value === 'string' && value.trim().length > 0 ? value : null;
+};
+
+export const isReviewSession = (session: Session | null | undefined): boolean =>
+  getOpenChamberMetadata(getSessionMetadata(session)).kind === 'review' && Boolean(getOriginalSessionID(session));
+
+export const withReviewSessionLink = (
+  metadata: SessionMetadataRecord,
+  reviewSessionID: string,
+): SessionMetadataRecord => {
+  const current = getOpenChamberMetadata(metadata);
+  return {
+    ...metadata,
+    openchamber: {
+      ...current,
+      reviewSessionID,
+    },
+  };
+};
+
+export const withReviewSessionMarker = (
+  metadata: SessionMetadataRecord,
+  originalSessionID: string,
+): SessionMetadataRecord => {
+  const current = getOpenChamberMetadata(metadata);
+  return {
+    ...metadata,
+    openchamber: {
+      ...current,
+      kind: 'review' as const,
+      originalSessionID,
+    },
+  };
+};
+
+export const withoutReviewSessionLink = (
+  metadata: SessionMetadataRecord,
+  reviewSessionID: string,
+): SessionMetadataRecord => {
+  const current = getOpenChamberMetadata(metadata);
+  if (current.reviewSessionID !== reviewSessionID) return metadata;
+
+  const restOpenChamber = { ...current };
+  delete restOpenChamber.reviewSessionID;
+  const next: SessionMetadataRecord = { ...metadata };
+  if (Object.keys(restOpenChamber).length > 0) {
+    next.openchamber = restOpenChamber;
+  } else {
+    delete next.openchamber;
+  }
+  return next;
+};
diff --git a/packages/ui/src/stores/useGlobalSessionsStore.ts b/packages/ui/src/stores/useGlobalSessionsStore.ts
index c6dec01a..67135c17 100644
--- a/packages/ui/src/stores/useGlobalSessionsStore.ts
+++ b/packages/ui/src/stores/useGlobalSessionsStore.ts
@@ -122,6 +122,7 @@ const getSessionSignature = (session: Session): string => {
     session.time?.updated ?? 0,
     session.time?.archived ?? 0,
     session.share?.url ?? '',
+    JSON.stringify((session as Session & { metadata?: unknown }).metadata ?? null),
     resolveGlobalSessionDirectory(session) ?? '',
   ].join(':');
 };
diff --git a/packages/ui/src/sync/session-actions.ts b/packages/ui/src/sync/session-actions.ts
index f4360c85..54acf6e7 100644
--- a/packages/ui/src/sync/session-actions.ts
+++ b/packages/ui/src/sync/session-actions.ts
@@ -16,6 +16,13 @@ import { isSyntheticPart } from "@/lib/messages/synthetic"
 import { materializeSessionSnapshots } from "./materialization"
 import { stripMessageDiffSnapshots } from "./sanitize"
 import { sessionEvents } from "@/lib/sessionEvents"
+import {
+  getOriginalSessionID,
+  getSessionMetadata,
+  isReviewSession,
+  withoutReviewSessionLink,
+  type SessionMetadataRecord,
+} from "@/lib/sessionReviewMetadata"
 
 const MESSAGE_REFETCH_LIMIT = 200
 const MESSAGE_REFETCH_SKIP_PARTS = new Set(["patch", "step-start", "step-finish"])
@@ -331,11 +338,13 @@ export async function createSession(
   title?: string,
   directoryOverride?: string | null,
   parentID?: string | null,
+  metadata?: Record<string, unknown>,
 ): Promise<Session | null> {
   try {
     const session = await opencodeClient.createSession({
       title,
       parentID: parentID ?? undefined,
+      metadata,
     }, directoryOverride ?? dir())
 
     const sessionDirectory = (session as { directory?: string | null }).directory ?? null
@@ -354,6 +363,42 @@ export async function createSession(
   }
 }
 
+export async function patchSessionMetadata(
+  sessionId: string,
+  directory: string | null | undefined,
+  updater: (metadata: SessionMetadataRecord) => SessionMetadataRecord,
+): Promise<Session> {
+  const targetDirectory = directory ?? getSessionDirectory(sessionId)
+  const current = await opencodeClient.getSession(sessionId, targetDirectory)
+  const nextMetadata = updater(getSessionMetadata(current))
+  const updated = await opencodeClient.updateSession(sessionId, { metadata: nextMetadata }, targetDirectory)
+  useGlobalSessionsStore.getState().upsertSession(updated)
+  const sessionDirectory = (updated as { directory?: string | null }).directory ?? targetDirectory
+  if (sessionDirectory) registerSessionDirectory(updated.id, sessionDirectory)
+  return updated
+}
+
+async function cleanupReviewMetadataBeforeDelete(sessionId: string, directory?: string | null): Promise<void> {
+  let session: Session
+  try {
+    session = await opencodeClient.getSession(sessionId, directory ?? getSessionDirectory(sessionId))
+  } catch {
+    return
+  }
+  if (!isReviewSession(session)) return
+  const originalSessionID = getOriginalSessionID(session)
+  if (!originalSessionID) return
+  try {
+    await patchSessionMetadata(originalSessionID, directory ?? getSessionDirectory(originalSessionID), (metadata) =>
+      withoutReviewSessionLink(metadata, sessionId),
+    )
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (/not found/i.test(message)) return
+    console.warn("[session-actions] review metadata cleanup failed before delete", error)
+  }
+}
+
 /** Optimistically remove a session from every live child store that has it. */
 function optimisticRemoveSession(sessionId: string, preferredDirectory?: string): SessionListSnapshot[] {
   if (!_childStores) return []
@@ -408,6 +453,7 @@ export async function deleteSession(sessionId: string, _options?: Record<string,
     ui.setCurrentSession(null)
   }
   try {
+    await cleanupReviewMetadataBeforeDelete(sessionId, sessionDirectory)
     const deleted = await opencodeClient.deleteSession(sessionId, sessionDirectory)
     if (deleted !== true) {
       throw new Error("session.delete failed: server did not confirm deletion")
@@ -431,6 +477,7 @@ export async function deleteSessionInDirectory(sessionId: string, directory: str
   const ui = useSessionUIStore.getState()
   if (ui.currentSessionId === sessionId) ui.setCurrentSession(null)
   try {
+    await cleanupReviewMetadataBeforeDelete(sessionId, directory)
     const deleted = await opencodeClient.deleteSession(sessionId, directory)
     if (deleted !== true) {
       throw new Error("session.delete failed: server did not confirm deletion")
@@ -544,6 +591,7 @@ export async function optimisticSend(input: {
   agent?: string
   directory?: string | null
   files?: Array<{ type: "file"; mime: string; url: string; filename: string }>
+  onOptimisticInsert?: () => void
   /** The actual API call — receives the optimistic messageID so the server can use the same ID */
   send: (messageID: string) => Promise<void>
 }): Promise<void> {
@@ -588,6 +636,7 @@ export async function optimisticSend(input: {
     message: optimisticMessage,
     parts: optimisticParts,
   })
+  input.onOptimisticInsert?.()
 
   // Set busy status
   const current = store.getState()
diff --git a/packages/ui/src/sync/session-ui-store.ts b/packages/ui/src/sync/session-ui-store.ts
index 261a0b86..2e8311ae 100644
--- a/packages/ui/src/sync/session-ui-store.ts
+++ b/packages/ui/src/sync/session-ui-store.ts
@@ -268,7 +268,7 @@ export type SessionUIState = {
     options?: SendMessageOptions,
   ) => Promise<void>
 
-  createSession: (title?: string, directoryOverride?: string | null, parentID?: string | null) => Promise<Session | null>
+  createSession: (title?: string, directoryOverride?: string | null, parentID?: string | null, metadata?: Record<string, unknown>) => Promise<Session | null>
   deleteSession: (id: string, options?: Record<string, unknown>) => Promise<boolean>
   deleteSessions: (ids: string[], options?: Record<string, unknown>) => Promise<{ deletedIds: string[]; failedIds: string[] }>
   archiveSession: (id: string) => Promise<boolean>
@@ -998,14 +998,14 @@ export const useSessionUIStore = create<SessionUIState>()((set, get) => ({
   // ---------------------------------------------------------------------------
   // createSession
   // ---------------------------------------------------------------------------
-  createSession: async (title, directoryOverride, parentID) => {
+  createSession: async (title, directoryOverride, parentID, metadata) => {
     const draft = get().newSessionDraft
     const targetFolderId = draft.targetFolderId
     get().closeNewSessionDraft()
 
     try {
       const dir = directoryOverride ?? opencodeClient.getDirectory()
-      const session = await createSessionAction(title, dir, parentID ?? null)
+      const session = await createSessionAction(title, dir, parentID ?? null, metadata)
       if (!session) return null
 
       if (targetFolderId) {
diff --git a/review-flow-implementation-plan.md b/review-flow-implementation-plan.md
new file mode 100644
index 00000000..d9156d04
--- /dev/null
+++ b/review-flow-implementation-plan.md
@@ -0,0 +1,766 @@
+# Review Flow Implementation Plan
+
+## Goal
+
+Build an end-to-end OpenChamber review handoff flow that lets one session implement changes and another normal session review them, with OpenChamber metadata connecting the two sessions invisibly.
+
+The agents must not see session IDs, metadata, linked-session wording, or routing details. They should only receive natural prompts:
+
+- Review session initial prompt: a handoff plus an instruction to review it.
+- Review-to-implementer prompt: another agent reviewed the changes and left feedback; resolve relevant issues.
+- Implementer-to-review prompt: the agent implementing changes responded to previous feedback; review latest state again.
+
+The review session is not a child/subsession. It is a normal session in the same directory as the original session.
+
+## Proposed Command Name
+
+Do not use `/review`, because that overlaps with OpenCode's default review command semantics.
+
+Use `/handoff-review` unless we choose a shorter name before implementation.
+
+Other acceptable names if `/handoff-review` feels too long:
+
+- `/review-handoff`
+- `/ask-review`
+- `/start-review`
+
+This plan assumes `/handoff-review`.
+
+## Existing Code Paths To Reuse
+
+### Slash Command Routing
+
+Relevant files:
+
+- `packages/ui/src/sync/session-ui-store.ts`
+- `packages/ui/src/lib/opencode/client.ts`
+- `packages/ui/src/lib/magicPrompts.ts`
+
+Current behavior:
+
+- `routeMessage(...)` detects messages starting with `/`.
+- It checks command metadata from `getDirectoryState(requestDirectory)?.command` and `useCommandsStore.getState().commands`.
+- If the command exists, it uses `optimisticSend(...)` and calls `opencodeClient.sendCommand(...)`.
+- `opencodeClient.sendCommand(...)` calls SDK `client.session.command(...)` with `sessionID`, `command`, `arguments`, selected model, selected agent, variant, files, and client-generated `messageID`.
+
+Reuse this for invoking the handoff-generation command. The review flow should not invent a separate command transport.
+
+### Magic Prompt Registry
+
+Relevant file:
+
+- `packages/ui/src/lib/magicPrompts.ts`
+
+Current examples:
+
+- `session.summary.visible`
+- `session.summary.instructions`
+- `session.review.visible`
+- `session.review.instructions`
+- `git.commit.generate.visible`
+- `git.commit.generate.instructions`
+
+Add new prompt entries for this flow instead of hardcoding long prompts in components/actions.
+
+Needed prompt entries:
+
+- `session.reviewHandoff.visible`
+- `session.reviewHandoff.instructions`
+- `session.reviewSession.visible`
+- `session.reviewSession.instructions` if we need hidden instructions for the review session starter prompt
+- `session.reviewFeedbackToImplementer.visible`
+- `session.implementationResponseToReviewer.visible`
+
+The two cross-session prompts must match the agreed wording closely.
+
+Review feedback sent back to the original session:
+
+```md
+Another agent reviewed your changes and left the feedback below.
+
+Please review the feedback, resolve the relevant issues, and explain what you changed.
+
+<review feedback>
+```
+
+Implementation response sent back to the review session:
+
+```md
+The agent implementing the changes has responded to the previous review feedback.
+
+Please review the latest state again and report any remaining issues.
+
+<implementation response / latest assistant message>
+```
+
+Initial review session prompt should be similar to:
+
+```md
+Please review the changes described in this handoff.
+
+Focus on correctness, regressions, missing implementation, missing tests, and whether the implementation satisfies the stated intent. Provide concise, actionable feedback for the agent implementing the changes.
+
+<handoff>
+```
+
+The handoff-generation prompt should be based on the summary command, but explicitly include the user's intent and enough implementation context for another agent to review.
+
+### Handoff Generation Concept
+
+Relevant existing prompt:
+
+- `session.summary.instructions` in `packages/ui/src/lib/magicPrompts.ts`
+
+Current summary instructions already include:
+
+- completed work
+- in-progress work
+- modified files and why
+- open questions and next steps
+- user requests, constraints, preferences
+- technical decisions and rationale
+
+The new handoff prompt should keep those ideas and make intent explicit:
+
+- What the user wanted and why
+- What was implemented
+- What files changed and why
+- Important design choices
+- Known limitations or uncertainty
+- Validation/test status if known from the session
+- Anything the reviewer should pay special attention to
+
+This is an implementation detail, not a risk. The prompt should be specific enough that the review agent can judge intent and implementation without needing private OpenChamber routing context.
+
+### Active Session Generation Concept
+
+Relevant files:
+
+- `packages/ui/src/lib/gitApi.ts`
+- `packages/ui/src/components/views/GitView.tsx`
+
+Current commit-message generation uses:
+
+- `resolveSessionGenerationContext()` to find current session, model, agent, and variant.
+- `runStructuredGenerationInActiveSession(...)` to send a visible prompt plus hidden synthetic instructions to the active session.
+- `extractAssistantText(...)` and JSON parsing to get output from the assistant response.
+
+Important difference for review flow:
+
+- Commit generation uses `client.session.prompt(...)` and receives the response directly.
+- Slash commands use `client.session.command(...)`, are effectively fire-and-forget from the UI path, and rely on SSE to populate messages/status.
+
+For `/handoff-review`, prefer the visible slash command path so the original session contains the generated handoff. Then wait for the resulting assistant output through sync state. Reuse the commit-generation concepts for:
+
+- selected model/agent/variant resolution
+- extracting text from assistant message parts
+- forcing chat scroll if useful
+- timeout/error handling style
+
+Create a small reusable helper for waiting for the next completed assistant text after a known user command message ID.
+
+### Session Create/Update/Delete
+
+Relevant files:
+
+- `packages/ui/src/lib/opencode/client.ts`
+- `packages/ui/src/sync/session-actions.ts`
+- `packages/ui/src/sync/event-reducer.ts`
+- `packages/ui/src/stores/useGlobalSessionsStore.ts`
+
+Current behavior:
+
+- `opencodeClient.createSession(...)` calls `client.session.create(...)` using the legacy OpenCode session API.
+- OpenCode supports `metadata` on that API, but OpenChamber currently only forwards `parentID` and `title`.
+- `opencodeClient.updateSession(...)` currently only forwards `title` and `time.archived`.
+- OpenCode `metadata` update replaces the whole metadata object. It does not deep-merge.
+- `deleteSession(...)` and `deleteSessionInDirectory(...)` optimistically remove the session, then call `opencodeClient.deleteSession(...)`, and restore snapshots on failure.
+- `event-reducer.ts` replaces session objects from `session.created` and `session.updated` events.
+
+Add metadata support here first. The review flow depends on it.
+
+### Context Panel Session Tabs
+
+Relevant files:
+
+- `packages/ui/src/stores/useUIStore.ts`
+- `packages/ui/src/components/session/sidebar/SessionNodeItem.tsx`
+- `packages/ui/src/components/layout/ContextPanel.tsx`
+- `packages/ui/src/components/chat/message/MessageBody.tsx`
+- `packages/ui/src/components/chat/message/parts/ToolPart.tsx`
+
+Current behavior:
+
+- `useUIStore.openContextPanelTab(directory, tab)` opens or upserts context panel tabs.
+- Chat tabs use `mode: 'chat'`.
+- Existing dedupe key convention for session chat tabs is `session:<sessionID>`.
+- Sidebar already opens a session in the side panel with:
+
+```ts
+openContextPanelTab(sessionDirectory, {
+  mode: 'chat',
+  dedupeKey: `session:${session.id}`,
+  label: sessionTitle,
+})
+```
+
+Reuse the same convention for opening the review session in the context panel.
+
+### Assistant Message Action Buttons
+
+Relevant file:
+
+- `packages/ui/src/components/chat/message/MessageBody.tsx`
+
+Current behavior:
+
+- `AssistantMessageActionButtons` renders icon-only buttons for copy, save image, and TTS.
+- The buttons use shared `Button`, `Tooltip`, and `Icon` components.
+- The shared icon sprite already contains `arrow-left-right`.
+
+Extend this action area with an optional review-transfer action. Do not import icons directly from Remixicon.
+
+## Metadata Contract
+
+Use a namespaced metadata object so we do not collide with user or upstream metadata.
+
+Original session metadata:
+
+```ts
+{
+  openchamber: {
+    reviewSessionID: string
+  }
+}
+```
+
+Review session metadata:
+
+```ts
+{
+  openchamber: {
+    kind: 'review'
+    originalSessionID: string
+  }
+}
+```
+
+Rules:
+
+- Only one review session per original session.
+- If original metadata already has `openchamber.reviewSessionID`, reuse that session instead of creating a new review session.
+- The review session must not have `parentID` set to the original session.
+- Both sessions must stay in the same directory.
+- Metadata is internal routing state only. Never include it in prompts.
+- Metadata updates must preserve unrelated metadata keys.
+
+Recommended helpers:
+
+```ts
+type OpenChamberSessionMetadata = {
+  openchamber?: {
+    kind?: 'review'
+    originalSessionID?: string
+    reviewSessionID?: string
+  }
+  [key: string]: unknown
+}
+```
+
+Helper functions should live in a focused module, for example:
+
+- `packages/ui/src/lib/sessionReviewMetadata.ts`
+
+Functions:
+
+- `getOpenChamberMetadata(session)`
+- `isReviewSession(session)`
+- `getOriginalSessionID(session)`
+- `getReviewSessionID(session)`
+- `withReviewSessionLink(metadata, reviewSessionID)`
+- `withReviewSessionMarker(metadata, originalSessionID)`
+- `withoutReviewSessionLink(metadata, reviewSessionID)`
+
+The helpers should clone only the metadata branch they change and preserve all unrelated metadata.
+
+## Implementation Steps
+
+### 1. Load Required Skills Before Editing
+
+When implementing this plan, load these skills before changing code:
+
+- `ui-api-decoupling` because the work changes SDK data access and session API wrapper behavior.
+- `theme-system` because the work adds a UI button/icon.
+- `locale-ui-patterns` because the work adds tooltips, aria labels, toasts, and command text.
+
+If the final implementation touches Settings magic prompt UI, also load:
+
+- `settings-ui-patterns`
+
+### 2. Add Metadata Support To OpenCode Client Wrapper
+
+File:
+
+- `packages/ui/src/lib/opencode/client.ts`
+
+Change `createSession` signature from:
+
+```ts
+async createSession(params?: { parentID?: string; title?: string }, directory?: string | null): Promise<Session>
+```
+
+to:
+
+```ts
+async createSession(
+  params?: {
+    parentID?: string
+    title?: string
+    metadata?: Record<string, unknown>
+  },
+  directory?: string | null,
+): Promise<Session>
+```
+
+Forward `metadata: params?.metadata` only when it is defined.
+
+Change `updateSession` patch type from:
+
+```ts
+patch: { title?: string; time?: { archived?: number | null } }
+```
+
+to:
+
+```ts
+patch: {
+  title?: string
+  metadata?: Record<string, unknown>
+  time?: { archived?: number | null }
+}
+```
+
+Forward `metadata` when defined.
+
+Important: this method should still replace metadata because the upstream API replaces metadata. Do not hide this with an implicit merge here. Add merge behavior in a separate helper so call sites are explicit.
+
+### 3. Make Session Types Metadata-Aware In OpenChamber
+
+OpenCode SDK response types should include metadata in the current v2 SDK legacy `Session`, but verify local imports and generated types used by OpenChamber.
+
+Files to inspect/update:
+
+- `packages/ui/src/stores/types/sessionTypes.ts`
+- Any local `Session` wrapper/normalizer if present
+- `packages/ui/src/sync/sanitize.ts`
+- `packages/ui/src/sync/event-reducer.ts`
+- `packages/ui/src/stores/useGlobalSessionsStore.ts`
+
+Goal:
+
+- `session.metadata` should survive list, get, create, update, SSE event replacement, global sessions, and reconnect recovery.
+- Do not strip `metadata` in sanitation helpers.
+- Do not create new broad store subscriptions. Use leaf selectors where UI only needs review metadata for one session.
+
+### 4. Add Explicit Metadata Merge Helpers
+
+Add a helper, likely in `packages/ui/src/sync/session-actions.ts` or a small module imported by it:
+
+```ts
+async function patchSessionMetadata(
+  sessionId: string,
+  directory: string | null | undefined,
+  updater: (metadata: Record<string, unknown>) => Record<string, unknown>,
+): Promise<Session>
+```
+
+Behavior:
+
+1. Read the current session with `opencodeClient.getSession(sessionId)` using the correct directory.
+2. Read `current.metadata ?? {}`.
+3. Apply updater.
+4. Call `opencodeClient.updateSession(sessionId, { metadata: nextMetadata }, directory)`.
+5. Upsert the returned session into `useGlobalSessionsStore` and the relevant child store if needed.
+
+Do not swallow fetch/update errors. Callers need to know if metadata linkage failed.
+
+### 5. Add Review Flow Magic Prompts
+
+File:
+
+- `packages/ui/src/lib/magicPrompts.ts`
+
+Add these prompt records:
+
+1. `session.reviewHandoff.visible`
+
+Suggested template:
+
+```txt
+Prepare a handoff for another agent to review this work.
+```
+
+2. `session.reviewHandoff.instructions`
+
+Suggested template:
+
+```txt
+Produce a review handoff for another agent. Do not compact or mutate session history. Your output is an assistant message that OpenChamber will send to a separate reviewer agent.
+
+Include:
+- The user's original intent and any later clarifications that changed the intent
+- What was implemented and why
+- Files changed, with brief purpose per file
+- Important design decisions and tradeoffs
+- Validation/tests run, if known
+- Known gaps, uncertainty, or areas the reviewer should inspect closely
+
+Formatting:
+- Concise markdown with clear sections
+- No preamble like "Here is a handoff"
+- Do not mention OpenChamber metadata, linked sessions, session IDs, or routing
+- Respond in the same language the user used most in the conversation
+```
+
+3. `session.reviewSession.visible`
+
+Suggested template with `{{handoff}}` placeholder:
+
+```txt
+Please review the changes described in this handoff.
+
+Focus on correctness, regressions, missing implementation, missing tests, and whether the implementation satisfies the stated intent. Provide concise, actionable feedback for the agent implementing the changes.
+
+{{handoff}}
+```
+
+4. `session.reviewFeedbackToImplementer.visible`
+
+Suggested template with `{{review_feedback}}` placeholder:
+
+```txt
+Another agent reviewed your changes and left the feedback below.
+
+Please review the feedback, resolve the relevant issues, and explain what you changed.
+
+{{review_feedback}}
+```
+
+5. `session.implementationResponseToReviewer.visible`
+
+Suggested template with `{{implementation_response}}` placeholder:
+
+```txt
+The agent implementing the changes has responded to the previous review feedback.
+
+Please review the latest state again and report any remaining issues.
+
+{{implementation_response}}
+```
+
+### 6. Add Localized UI Strings
+
+Files:
+
+- `packages/ui/src/lib/i18n/messages/en.ts`
+- Other locale files as required by the project pattern
+
+Add strings for:
+
+- Command autocomplete description for `/handoff-review`.
+- Review flow button aria label on review session: “Send review feedback to implementing agent”.
+- Review flow button aria label on original session: “Send implementation response to reviewing agent”.
+- Tooltip text for both directions.
+- Toasts for starting handoff generation, review session creation/reuse, transfer success, transfer failure, missing linked session, missing assistant text.
+
+Follow locale-ui-patterns. Do not hardcode user-facing text inside components.
+
+### 7. Register The New OpenChamber Slash Command
+
+There are two possible implementation paths. Pick the one matching how OpenChamber-owned commands are currently registered.
+
+Likely locations:
+
+- `packages/ui/src/lib/magicPrompts.ts`
+- command autocomplete/store code around `useCommandsStore`
+- command rendering in `ChatInput` / command autocomplete components
+
+The command should appear as `/handoff-review` in OpenChamber command autocomplete.
+
+It should be treated as an OpenChamber flow command, not only a raw OpenCode command, because after the handoff assistant output completes OpenChamber must create/reuse/open/send to the review session.
+
+Implementation options:
+
+1. Intercept `/handoff-review` in `routeMessage(...)` before normal OpenCode command lookup.
+2. Add it to the command store as an OpenChamber-owned command with a handler.
+
+Prefer the smallest approach consistent with existing command architecture.
+
+### 8. Implement Handoff Generation And Wait Helper
+
+Add a helper that starts the handoff command in the original session and resolves with the assistant handoff text.
+
+Possible module:
+
+- `packages/ui/src/lib/reviewFlow.ts`
+
+Inputs:
+
+```ts
+{
+  originalSessionID: string
+  directory: string
+  providerID: string
+  modelID: string
+  agent?: string
+  variant?: string
+}
+```
+
+Flow:
+
+1. Render `session.reviewHandoff.visible` and `session.reviewHandoff.instructions`.
+2. Send a user message to the original session using `opencodeClient.sendMessage(...)` or the existing command route, depending on final command integration.
+3. Include the visible handoff request as the visible user text.
+4. Include hidden instructions as synthetic additional part if using `sendMessage(...)`.
+5. Capture the generated user message ID.
+6. Wait until a later assistant message for the same session is complete and has text.
+7. Extract text with the same idea as `flattenAssistantTextParts(...)` / `extractAssistantText(...)`.
+8. Timeout with a clear failure if no handoff arrives.
+
+Waiting rules:
+
+- Prefer sync store state over polling the server repeatedly.
+- Use existing `getSyncMessages(sessionID)` and `getSyncParts(sessionID)` from `sync-refs` if they expose enough data.
+- If a subscription-based wait is not easy, use a bounded interval that reads sync refs and stops on timeout or completion.
+- Ensure it waits for assistant completion, not just first streaming text.
+- Avoid broad store subscriptions in React components.
+
+### 9. Create Or Reuse The Review Session
+
+After handoff text is available:
+
+1. Read original session with `opencodeClient.getSession(originalSessionID)`.
+2. Read `original.metadata.openchamber.reviewSessionID`.
+3. If it exists:
+   - Try to get that review session in the same directory.
+   - If it exists and has `metadata.openchamber.kind === 'review'`, reuse it.
+   - If it is missing/deleted, clear the stale link and create a new review session.
+4. If it does not exist, create a new normal session in the same directory with metadata:
+
+```ts
+{
+  openchamber: {
+    kind: 'review',
+    originalSessionID,
+  }
+}
+```
+
+5. Patch original session metadata with:
+
+```ts
+{
+  openchamber: {
+    reviewSessionID: reviewSession.id,
+  }
+}
+```
+
+Preserve unrelated metadata on both sessions.
+
+If metadata patching original fails after creating review session, report failure clearly. Do not silently proceed with an unlinked session.
+
+### 10. Send Initial Prompt To Review Session
+
+After create/reuse:
+
+1. Render `session.reviewSession.visible` with `handoff`.
+2. Send it to the review session as a normal user message.
+3. Use the same provider/model/agent/variant policy as the current session unless product decision says otherwise.
+4. Do not mention session IDs or linked sessions.
+
+Important:
+
+- If reusing an existing review session, still send the new handoff prompt into it.
+- Reuse does not mean “do nothing”; it means continue the same review conversation.
+
+### 11. Open Review Session In Context Panel
+
+Use:
+
+```ts
+useUIStore.getState().openContextPanelTab(directory, {
+  mode: 'chat',
+  dedupeKey: `session:${reviewSession.id}`,
+  label: reviewSession.title,
+})
+```
+
+This should happen after the review session exists and the initial prompt has been sent, or immediately after creation if sending happens asynchronously but errors are still surfaced.
+
+### 12. Add Cross-Session Transfer Button On Assistant Messages
+
+File:
+
+- `packages/ui/src/components/chat/message/MessageBody.tsx`
+
+Add optional props to `AssistantMessageActionButtons`:
+
+```ts
+reviewTransferAction?: {
+  ariaLabel: string
+  tooltip: string
+  disabled?: boolean
+  onClick: () => Promise<void> | void
+}
+```
+
+Render an icon-only button with:
+
+```tsx
+<Icon name="arrow-left-right" ... />
+```
+
+Visibility rules:
+
+- Only assistant messages.
+- Only messages with copyable text.
+- In a review session: show button to send review feedback to the original session.
+- In an original session with `metadata.openchamber.reviewSessionID`: show button to send implementation response to the review session.
+- Do not show in mini-chat if that surface should avoid extra controls; follow current action-button surface rules.
+
+To avoid button spam:
+
+- Preferred first implementation: show on assistant messages where normal assistant action buttons already show.
+- Do not add the button to user messages.
+- If this feels too noisy in testing, narrow to latest completed assistant message per session as a follow-up, but not required for initial end-to-end implementation.
+
+### 13. Implement Review Feedback Transfer
+
+When clicking the button in a review session:
+
+1. Get current review session metadata.
+2. Resolve `originalSessionID`.
+3. Extract the clicked assistant message text.
+4. Render `session.reviewFeedbackToImplementer.visible` with `review_feedback`.
+5. Send it as a normal user message into the original session.
+6. Use original session directory.
+7. Optionally open/focus the original session or leave context panel as-is. The agreed behavior only requires sending.
+8. Show success/failure toast.
+
+Message sent to the agent must be exactly natural-language feedback, not routing data.
+
+### 14. Implement Implementation Response Transfer
+
+When clicking the button in the original session:
+
+1. Get original session metadata.
+2. Resolve `reviewSessionID`.
+3. Extract the clicked assistant message text.
+4. Render `session.implementationResponseToReviewer.visible` with `implementation_response`.
+5. Send it as a normal user message into the review session.
+6. Use same directory.
+7. Open/focus the review session context panel tab, because review continuation happens there.
+8. Show success/failure toast.
+
+### 15. Cleanup Metadata When Deleting Review Session
+
+Files:
+
+- `packages/ui/src/sync/session-actions.ts`
+- `packages/ui/src/lib/opencode/client.ts`
+
+Before deleting a session:
+
+1. Read the session being deleted.
+2. If it is a review session and has `originalSessionID`, read the original session.
+3. If original metadata has `reviewSessionID` equal to the deleted review session ID, patch original metadata to remove it.
+4. Then delete the review session.
+
+Failure behavior:
+
+- If metadata cleanup fails, do not delete silently. Return failure and show the existing delete failure path/toast.
+- If original session no longer exists, continue deleting the review session; there is nothing to clean.
+- If delete fails after metadata cleanup succeeded, restore the original metadata link as part of rollback if possible. At minimum, log and surface the delete failure.
+
+Also apply this to `deleteSessionInDirectory(...)`.
+
+### 16. Cleanup Stale Link When Reusing Review Session
+
+If original metadata points to a review session that no longer exists:
+
+1. Patch original metadata to remove stale `reviewSessionID`.
+2. Create a fresh review session.
+3. Patch original metadata with the fresh review session ID.
+
+This is not a background reconciler. It only happens when the user starts the review flow.
+
+### 17. Tests
+
+Add focused tests for helpers and flow boundaries.
+
+Likely files:
+
+- New `packages/ui/src/lib/sessionReviewMetadata.test.ts`
+- Existing `packages/ui/src/sync/session-actions.test.ts`
+- Component test around `MessageBody` only if nearby test patterns exist
+
+Test cases:
+
+1. Metadata helper marks review session without removing unrelated metadata.
+2. Metadata helper links original session without removing unrelated metadata.
+3. Metadata helper removes review link only when it matches the deleted review session ID.
+4. `createSession` forwards metadata to SDK client.
+5. `updateSession` forwards metadata to SDK client.
+6. Review flow reuses existing review session ID instead of creating another.
+7. Review flow clears stale review session ID when referenced review session is missing.
+8. Delete review session cleans original metadata before deleting.
+9. Transfer prompt for review-to-implementer contains no session ID / metadata / linked-session wording.
+10. Transfer prompt for implementer-to-reviewer contains no session ID / metadata / linked-session wording.
+
+### 18. Validation
+
+Run:
+
+```sh
+bun run type-check
+bun run lint
+```
+
+Manual validation checklist:
+
+1. Start `/handoff-review` in a normal session.
+2. Confirm a handoff assistant message appears in original session.
+3. Confirm a normal review session is created in the same directory, not as a child.
+4. Confirm original metadata has `openchamber.reviewSessionID`.
+5. Confirm review metadata has `openchamber.kind === 'review'` and `openchamber.originalSessionID`.
+6. Confirm review session opens in context panel.
+7. Confirm review session receives the initial handoff review prompt.
+8. Confirm arrow-left-right appears on review assistant message actions.
+9. Click it and confirm original session receives the agreed review feedback prompt.
+10. Confirm arrow-left-right appears on original assistant message actions when original has review metadata.
+11. Click it and confirm review session receives the agreed implementation response prompt.
+12. Run `/handoff-review` again on the same original session and confirm it reuses the existing review session.
+13. Delete the review session and confirm original metadata link is removed.
+14. Delete original session and confirm no review cleanup crash occurs.
+
+## Non-Goals
+
+- Do not add a review status state machine.
+- Do not allow multiple review sessions for one original session in this first implementation.
+- Do not expose metadata, linked sessions, or session IDs to agents.
+- Do not use parent/child session relationships for this feature.
+- Do not change OpenCode core or SDK unless OpenChamber cannot access metadata from the existing SDK types.
+- Do not make a background metadata reconciler.
+
+## Main Implementation Risks To Watch While Coding
+
+These are coding concerns, not product blockers:
+
+- Metadata replacement must not drop unrelated metadata.
+- Event/store sanitation must not strip `metadata` from session records.
+- The handoff wait helper must wait for completed assistant output, not first streaming text.
+- Cross-session sends must use the correct directory dynamically, not cached closure values.
+- Message action buttons must not subscribe broad chat rows to global session collections.
+- Delete cleanup should not delete the review session if cleanup fails in a way that would leave confusing metadata behind.