From 0ce9c6ec275da7d40bb7e235571cdfeeb02eb791 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yohan=20Gon=C3=A7alves?= <yohan.goncalves.pro@gmail.com>
Date: Thu, 30 Jul 2026 18:36:32 +0200
Subject: [PATCH] fix(hitl): approve/reject continues conversation,
 multi-tool-call panel, last-message gating

The HITL approve/reject flow was broken in the UI: clicking approve or
reject did not continue the conversation. Root causes on the frontend:

1. useSendMessage invalidated the React Query key ["messages", threadId]
   but the message list is driven by useThreadHistory whose key is
   ["history", threadId]. After a successful approve/reject nothing was
   refetched: the UI stayed frozen on the awaiting_hitl message.

2. HITLReviewPanel only handled toolCalls[0]; multi-tool-call interrupts
   were not supported (the backend now requires one decision per
   interrupted tool call).

3. The HITL panel rendered on ANY awaiting_hitl message, not only the
   last one, so a stale panel reappeared on older messages after
   continuation.

4. Mutation errors were silently swallowed (no sendMessage.error display).

Changes:
- useSendMessage: invalidate ["history", threadId] (the correct key).
- ChatRequest: add HitlDecisionInput + decisions field (legacy
  tool_call_id+action kept for backward compat).
- HITLReviewPanel: render one decision row per tool call (Approve/Reject
  per call + optional reject reason), a single Submit button sends one
  mutation with { decisions: [...] }. Display sendMessage.error when the
  mutation fails. Extract ToolDecisionRow subcomponent to keep functions
  shallow (SonarQube S2004).
- ChatMessage: add isLast prop; render the HITL panel only on the last
  message. Render discreet HITL_DECISION badges in the timeline
  (Approved / Rejected: reason / Edited). Update memo comparator.
- MessageList: pass isLast={idx === entries.length - 1} to each entry.
- traceEvent: add HITL_DECISION to the TraceEventType enum (flows into
  chatApi VALID_EVENT_TYPES automatically).

Tests: frontend suite green (801 passed). 0 new SonarQube issues, 0 new
Trivy vulnerabilities.
---
 .../components/chat/ChatMessage.tsx           |  39 ++-
 .../components/chat/HITLReviewPanel.tsx       | 269 +++++++++++-------
 .../components/chat/MessageList.tsx           |   1 +
 src/application/hooks/chat/useSendMessage.ts  |   2 +-
 src/domain/entities/chat/chatRequest.ts       |   8 +
 src/domain/entities/chat/traceEvent.ts        |   1 +
 .../unit/components/chat/ChatMessage.test.tsx | 109 +++++++
 .../components/chat/HITLReviewPanel.test.tsx  | 153 ++++++----
 .../unit/components/chat/MessageList.test.tsx |  69 ++++-
 .../domain/entities/chat/traceEvent.test.ts   |  15 +-
 tests/unit/hooks/chat/useSendMessage.test.tsx |  66 ++++-
 11 files changed, 570 insertions(+), 162 deletions(-)

diff --git a/src/application/components/chat/ChatMessage.tsx b/src/application/components/chat/ChatMessage.tsx
index 679c237..2c233fb 100644
--- a/src/application/components/chat/ChatMessage.tsx
+++ b/src/application/components/chat/ChatMessage.tsx
@@ -20,6 +20,7 @@ interface ChatMessageProps {
   agentName: string;
   threadId?: string;
   events?: TraceEvent[];
+  isLast?: boolean;
 }
 
 interface SubagentTimeline {
@@ -89,7 +90,13 @@ function formatTimestamp(ts: string): string {
   }).format(date);
 }
 
-function ChatMessageImpl({ message, agentName, threadId, events }: Readonly<ChatMessageProps>) {
+function ChatMessageImpl({
+  message,
+  agentName,
+  threadId,
+  events,
+  isLast,
+}: Readonly<ChatMessageProps>) {
   const isHuman = message.role === MessageRole.HUMAN;
   const isAi = message.role === MessageRole.AI;
   const isAwaitingHitl = message.status === MessageStatus.AWAITING_HITL;
@@ -103,6 +110,10 @@ function ChatMessageImpl({ message, agentName, threadId, events }: Readonly<Chat
     () => (events ? parentToolEvents(events) : { toolCalls: [], toolResults: [] }),
     [events],
   );
+  const hitlDecisionEvents = useMemo(
+    () => (events ? events.filter((e) => e.type === TraceEventType.HITL_DECISION) : []),
+    [events],
+  );
 
   if (isHuman) {
     return (
@@ -160,6 +171,27 @@ function ChatMessageImpl({ message, agentName, threadId, events }: Readonly<Chat
               <div className="mt-2 flex flex-col gap-2" data-od-id="message-timeline">
                 <ThinkingBlock text={parentThinkingText} source={null} />
 
+                {hitlDecisionEvents.map((ev) => {
+                  const action = ev.name ?? "";
+                  let label = "✎ Edited";
+                  let className = "border-accent text-accent";
+                  if (action === "approve") {
+                    label = "✓ Approved";
+                    className = "border-success text-success";
+                  } else if (action === "reject") {
+                    label = ev.content ? `✗ Rejected: ${ev.content}` : "✗ Rejected";
+                    className = "border-danger text-danger";
+                  }
+                  return (
+                    <span
+                      key={ev.id}
+                      className={`inline-block w-fit border bg-surface px-2 py-1 font-mono text-xs ${className}`}
+                    >
+                      {label}
+                    </span>
+                  );
+                })}
+
                 {parentTools.toolCalls.map((call) => (
                   <ToolCallBadge
                     key={call.id}
@@ -191,7 +223,7 @@ function ChatMessageImpl({ message, agentName, threadId, events }: Readonly<Chat
             )}
           </div>
 
-          {isAwaitingHitl && message.tool_calls?.length && threadId && (
+          {isAwaitingHitl && !!message.tool_calls?.length && !!threadId && isLast && (
             <HITLReviewPanel toolCalls={message.tool_calls} threadId={threadId} />
           )}
         </article>
@@ -213,7 +245,8 @@ const ChatMessage = memo(ChatMessageImpl, (prev, next) => {
     prev.agentName === next.agentName &&
     prev.threadId === next.threadId &&
     prev.message === next.message &&
-    prev.events === next.events
+    prev.events === next.events &&
+    prev.isLast === next.isLast
   );
 });
 
diff --git a/src/application/components/chat/HITLReviewPanel.tsx b/src/application/components/chat/HITLReviewPanel.tsx
index da12d92..26db721 100644
--- a/src/application/components/chat/HITLReviewPanel.tsx
+++ b/src/application/components/chat/HITLReviewPanel.tsx
@@ -4,133 +4,202 @@ import { Button } from "@/application/components/ui/button";
 import { Input } from "@/application/components/ui/input";
 import { useSendMessage } from "@/application/hooks/chat/useSendMessage";
 import type { ToolCall } from "@/domain/entities/chat/message";
+import type { HitlDecisionInput } from "@/domain/entities/chat/chatRequest";
 
 interface HITLReviewPanelProps {
   toolCalls: ToolCall[];
   threadId: string;
 }
 
-type ReviewState = "idle" | "reviewing" | "rejecting";
+type DecisionAction = "approve" | "reject";
 
-export default function HITLReviewPanel({ toolCalls, threadId }: Readonly<HITLReviewPanelProps>) {
-  const [reviewState, setReviewState] = useState<ReviewState>("idle");
-  const [rejectReason, setRejectReason] = useState("");
-  const sendMessage = useSendMessage(threadId);
-
-  const toolName = toolCalls[0]?.name ?? "Unknown tool";
-  const toolCallId = toolCalls[0]?.id ?? "";
-
-  function handleApprove() {
-    sendMessage.mutate({
-      tool_call_id: toolCallId,
-      action: "approve",
-    });
-  }
-
-  function handleReject() {
-    if (reviewState !== "rejecting") {
-      setReviewState("rejecting");
-      return;
-    }
-
-    sendMessage.mutate(
-      {
-        tool_call_id: toolCallId,
-        action: "reject",
-        reason: rejectReason || "Rejected by user",
-      },
-      {
-        onSuccess: () => {
-          setReviewState("idle");
-          setRejectReason("");
-        },
-      },
-    );
-  }
-
-  if (reviewState === "idle") {
-    return (
-      <div data-od-id="hitl-panel" className="mt-2 border border-warn bg-bg">
-        <div className="flex items-center justify-between gap-2 px-3 py-2">
-          <div className="flex items-center gap-2">
-            <AlertTriangle className="h-4 w-4 text-warn" aria-hidden="true" />
-            <span className="font-mono text-xs text-fg">
-              Validation required: <span className="font-mono">{toolName}</span>
-            </span>
-          </div>
-          <Button
-            type="button"
-            variant="ghost"
-            size="sm"
-            onClick={() => setReviewState("reviewing")}
-          >
-            Review Data
-          </Button>
-        </div>
-      </div>
-    );
-  }
+interface ToolDecisionRowProps {
+  toolCall: ToolCall;
+  isRejecting: boolean;
+  rejectReason: string;
+  isPending: boolean;
+  onApprove: (id: string) => void;
+  onReject: (id: string) => void;
+  onReasonChange: (id: string, reason: string) => void;
+  onConfirmReject: () => void;
+}
 
+function ToolDecisionRow({
+  toolCall,
+  isRejecting,
+  rejectReason,
+  isPending,
+  onApprove,
+  onReject,
+  onReasonChange,
+  onConfirmReject,
+}: Readonly<ToolDecisionRowProps>) {
   return (
-    <div data-od-id="hitl-panel" className="mt-2 border border-warn bg-bg">
-      <div className="flex items-center gap-2 px-3 py-2">
-        <AlertTriangle className="h-4 w-4 text-warn" aria-hidden="true" />
-        <span className="font-mono text-xs text-fg">
-          Review: <span className="font-mono">{toolName}</span>
-        </span>
+    <div className="border-t border-border">
+      <div className="px-3 py-2">
+        <span className="font-mono text-xs text-fg">{toolCall.name}</span>
       </div>
-
-      {toolCalls[0]?.args && (
-        <pre className="overflow-x-auto border-t border-border bg-bg px-3 py-2 font-mono text-xs text-fg-2">
-          {JSON.stringify(toolCalls[0].args, null, 2)}
+      {toolCall.args && Object.keys(toolCall.args).length > 0 && (
+        <pre className="overflow-x-auto bg-bg px-3 py-2 font-mono text-xs text-fg-2">
+          {JSON.stringify(toolCall.args, null, 2)}
         </pre>
       )}
-
-      {reviewState === "rejecting" && (
-        <div className="flex gap-2 border-t border-border p-3">
-          <Input
-            type="text"
-            value={rejectReason}
-            onChange={(e) => setRejectReason(e.target.value)}
-            placeholder="Reason for rejection (optional)"
-            className="flex-1"
-          />
-        </div>
-      )}
-
-      <div className="flex gap-2 border-t border-border p-3">
+      <div className="flex flex-wrap gap-2 p-3">
         <Button
           type="button"
           variant="success"
           size="sm"
-          onClick={handleApprove}
-          disabled={sendMessage.isPending}
+          onClick={() => onApprove(toolCall.id)}
+          disabled={isPending}
         >
           <Check className="h-3.5 w-3.5" />
-          Approve
+          Approve {toolCall.name}
         </Button>
         <Button
           type="button"
           variant="destructive"
           size="sm"
-          onClick={handleReject}
-          disabled={sendMessage.isPending}
+          onClick={() => onReject(toolCall.id)}
+          disabled={isPending}
         >
           <X className="h-3.5 w-3.5" />
-          {reviewState === "rejecting" ? "Confirm Reject" : "Reject"}
-        </Button>
-        <Button
-          type="button"
-          variant="ghost"
-          size="sm"
-          onClick={() => {
-            setReviewState("idle");
-            setRejectReason("");
-          }}
-        >
-          Cancel
+          Reject {toolCall.name}
         </Button>
       </div>
+      {isRejecting && (
+        <div className="flex flex-wrap gap-2 border-t border-border p-3">
+          <Input
+            type="text"
+            value={rejectReason}
+            onChange={(e) => onReasonChange(toolCall.id, e.target.value)}
+            placeholder="Reason for rejection (optional)"
+            className="flex-1"
+          />
+          <Button
+            type="button"
+            variant="destructive"
+            size="sm"
+            onClick={onConfirmReject}
+            disabled={isPending}
+          >
+            Confirm Reject
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default function HITLReviewPanel({ toolCalls, threadId }: Readonly<HITLReviewPanelProps>) {
+  const [isReviewing, setIsReviewing] = useState(false);
+  const [decisions, setDecisions] = useState<Record<string, DecisionAction>>({});
+  const [reasons, setReasons] = useState<Record<string, string>>({});
+  const [rejectingId, setRejectingId] = useState<string | null>(null);
+  const sendMessage = useSendMessage(threadId);
+
+  function handleApprove(id: string) {
+    setDecisions((prev) => ({ ...prev, [id]: "approve" }));
+    setRejectingId(null);
+  }
+
+  function handleReject(id: string) {
+    setDecisions((prev) => ({ ...prev, [id]: "reject" }));
+    setRejectingId(id);
+  }
+
+  function handleReasonChange(id: string, reason: string) {
+    setReasons((prev) => ({ ...prev, [id]: reason }));
+  }
+
+  function buildDecisions(): HitlDecisionInput[] {
+    return toolCalls.map((tc) => {
+      const action = decisions[tc.id] ?? "approve";
+      if (action === "reject") {
+        const reason = reasons[tc.id];
+        if (reason) {
+          return { tool_call_id: tc.id, action: "reject", reason };
+        }
+        return { tool_call_id: tc.id, action: "reject" };
+      }
+      return { tool_call_id: tc.id, action: "approve" };
+    });
+  }
+
+  function handleSubmit() {
+    sendMessage.mutate({ decisions: buildDecisions() });
+    setIsReviewing(false);
+    setDecisions({});
+    setReasons({});
+    setRejectingId(null);
+  }
+
+  const hasToolCalls = toolCalls.length > 0;
+
+  return (
+    <div data-od-id="hitl-panel" className="mt-2 border border-warn bg-bg">
+      <div className="flex items-center justify-between gap-2 px-3 py-2">
+        <div className="flex items-center gap-2">
+          <AlertTriangle className="h-4 w-4 text-warn" aria-hidden="true" />
+          <span className="font-mono text-xs text-fg">Validation required</span>
+        </div>
+        {!isReviewing && hasToolCalls && (
+          <Button type="button" variant="ghost" size="sm" onClick={() => setIsReviewing(true)}>
+            Review Data
+          </Button>
+        )}
+      </div>
+
+      {hasToolCalls && isReviewing && (
+        <>
+          {toolCalls.map((tc) => (
+            <ToolDecisionRow
+              key={tc.id}
+              toolCall={tc}
+              isRejecting={rejectingId === tc.id}
+              rejectReason={reasons[tc.id] ?? ""}
+              isPending={sendMessage.isPending}
+              onApprove={handleApprove}
+              onReject={handleReject}
+              onReasonChange={handleReasonChange}
+              onConfirmReject={handleSubmit}
+            />
+          ))}
+        </>
+      )}
+      {hasToolCalls && !isReviewing && (
+        <div className="border-t border-border px-3 py-2">
+          {toolCalls.map((tc) => (
+            <div key={tc.id} className="font-mono text-xs text-fg">
+              {tc.name}
+            </div>
+          ))}
+        </div>
+      )}
+      {!hasToolCalls && (
+        <div className="border-t border-border px-3 py-2">
+          <span className="font-mono text-xs text-fg">Unknown tool</span>
+        </div>
+      )}
+
+      {sendMessage.isError && sendMessage.error && (
+        <div className="border-t border-danger p-3">
+          <p className="font-mono text-xs text-danger">{sendMessage.error.message}</p>
+        </div>
+      )}
+
+      {isReviewing && hasToolCalls && (
+        <div className="border-t border-border p-3">
+          <Button
+            type="button"
+            variant="default"
+            size="sm"
+            onClick={handleSubmit}
+            disabled={sendMessage.isPending}
+          >
+            Submit
+          </Button>
+        </div>
+      )}
     </div>
   );
 }
diff --git a/src/application/components/chat/MessageList.tsx b/src/application/components/chat/MessageList.tsx
index 76cb2df..83d331e 100644
--- a/src/application/components/chat/MessageList.tsx
+++ b/src/application/components/chat/MessageList.tsx
@@ -162,6 +162,7 @@ export default function MessageList({
           agentName={agentName}
           threadId={threadId}
           events={entry.events}
+          isLast={idx === entries.length - 1}
         />
       ))}
 
diff --git a/src/application/hooks/chat/useSendMessage.ts b/src/application/hooks/chat/useSendMessage.ts
index da80d1c..b12354f 100644
--- a/src/application/hooks/chat/useSendMessage.ts
+++ b/src/application/hooks/chat/useSendMessage.ts
@@ -12,7 +12,7 @@ export function useSendMessage(threadId: string | null) {
     },
     onSuccess: () => {
       if (threadId) {
-        queryClient.invalidateQueries({ queryKey: ["messages", threadId] });
+        queryClient.invalidateQueries({ queryKey: ["history", threadId] });
       }
     },
   });
diff --git a/src/domain/entities/chat/chatRequest.ts b/src/domain/entities/chat/chatRequest.ts
index ea2c248..9e18d1f 100644
--- a/src/domain/entities/chat/chatRequest.ts
+++ b/src/domain/entities/chat/chatRequest.ts
@@ -1,9 +1,17 @@
 export type HITLAction = "approve" | "reject" | "edit";
 
+export interface HitlDecisionInput {
+  tool_call_id: string;
+  action: HITLAction;
+  reason?: string;
+  edits?: Record<string, unknown>;
+}
+
 export interface ChatRequest {
   message?: string;
   tool_call_id?: string;
   action?: HITLAction;
   reason?: string;
   edits?: Record<string, unknown>;
+  decisions?: HitlDecisionInput[];
 }
diff --git a/src/domain/entities/chat/traceEvent.ts b/src/domain/entities/chat/traceEvent.ts
index 567b32a..07abc8f 100644
--- a/src/domain/entities/chat/traceEvent.ts
+++ b/src/domain/entities/chat/traceEvent.ts
@@ -5,6 +5,7 @@ export enum TraceEventType {
   CONTENT = "content",
   TOOL_CALL = "tool_call",
   TOOL_RESULT = "tool_result",
+  HITL_DECISION = "hitl_decision",
 }
 
 export interface TraceEvent {
diff --git a/tests/unit/components/chat/ChatMessage.test.tsx b/tests/unit/components/chat/ChatMessage.test.tsx
index ed718dd..ccc2baa 100644
--- a/tests/unit/components/chat/ChatMessage.test.tsx
+++ b/tests/unit/components/chat/ChatMessage.test.tsx
@@ -5,6 +5,14 @@ import ChatMessage from "@/application/components/chat/ChatMessage";
 import { createMessage, createTraceEvent } from "../../../fixtures/external";
 import { MessageRole, MessageStatus } from "@/domain/entities/chat/message";
 import { TraceEventType } from "@/domain/entities/chat/traceEvent";
+import type { ToolCall } from "@/domain/entities/chat/message";
+
+// The HITL panel is marked with `data-od-id="hitl-panel"` (project convention).
+// testing-library's default `getByTestId` matches `data-testid`, so we query
+// the custom attribute directly.
+function hitlPanel(container: HTMLElement): Element | null {
+  return container.querySelector('[data-od-id="hitl-panel"]');
+}
 
 describe("ChatMessage", () => {
   it("renders AI message with agent name and content", () => {
@@ -148,4 +156,105 @@ describe("ChatMessage", () => {
     expect(screen.getByText("Final answer")).toBeInTheDocument();
     expect(screen.getByText("security-auditor")).toBeInTheDocument();
   });
+
+  // ─── HITL refactor: isLast gating of the HITL panel ───────────────────────
+  // Contract: HITLReviewPanel is rendered ONLY when
+  //   isAwaitingHitl && message.tool_calls?.length && threadId && isLast
+  // Adding `isLast` prevents a stale panel from rendering on an older
+  // awaiting_hitl message once the conversation has continued.
+
+  const hitlToolCalls: ToolCall[] = [{ id: "tc-1", name: "x", args: {} }];
+
+  it("renders HITL panel when isLast is true and status is awaiting_hitl", () => {
+    const message = createMessage({
+      role: MessageRole.AI,
+      content: "Needs review",
+      status: MessageStatus.AWAITING_HITL,
+      tool_calls: hitlToolCalls,
+    });
+
+    const { container } = renderWithProviders(
+      <ChatMessage message={message} agentName="test-agent" threadId="t1" isLast={true} />,
+    );
+
+    expect(hitlPanel(container)).not.toBeNull();
+  });
+
+  it("does NOT render HITL panel when isLast is false", () => {
+    const message = createMessage({
+      role: MessageRole.AI,
+      content: "Needs review",
+      status: MessageStatus.AWAITING_HITL,
+      tool_calls: hitlToolCalls,
+    });
+
+    const { container } = renderWithProviders(
+      <ChatMessage message={message} agentName="test-agent" threadId="t1" isLast={false} />,
+    );
+
+    expect(hitlPanel(container)).toBeNull();
+  });
+
+  it("does NOT render HITL panel when status is not awaiting_hitl", () => {
+    const message = createMessage({
+      role: MessageRole.AI,
+      content: "Done",
+      status: MessageStatus.COMPLETED,
+      tool_calls: hitlToolCalls,
+    });
+
+    const { container } = renderWithProviders(
+      <ChatMessage message={message} agentName="test-agent" threadId="t1" isLast={true} />,
+    );
+
+    expect(hitlPanel(container)).toBeNull();
+  });
+
+  // ─── HITL refactor: HITL_DECISION badges in the timeline ──────────────────
+  // Contract: in the AI message timeline (hasTimeline block), each
+  // HITL_DECISION event renders a discreet badge with text derived from
+  // `event.name` (the action) and `event.content` (the reason for reject):
+  //   - approve  -> "✓ Approved"
+  //   - reject   -> "✗ Rejected: {reason}"
+  //   - edit     -> "✎ Edited"
+  // The badge lives inside the `message-timeline` div. These tests assert the
+  // badge text is present (case-insensitive); exact styling is left to the
+  // implementation.
+
+  it("renders HITL_DECISION badge for an approved event", () => {
+    const message = createMessage({
+      role: MessageRole.AI,
+      content: "Continued",
+    });
+    const approveEvent = createTraceEvent({
+      type: TraceEventType.HITL_DECISION,
+      name: "approve",
+      content: null,
+    });
+
+    renderWithProviders(
+      <ChatMessage message={message} agentName="test-agent" events={[approveEvent]} />,
+    );
+
+    expect(screen.getByText(/approved/i)).toBeInTheDocument();
+  });
+
+  it("renders HITL_DECISION badge for a rejected event with the reason", () => {
+    const message = createMessage({
+      role: MessageRole.AI,
+      content: "Continued",
+    });
+    const rejectEvent = createTraceEvent({
+      type: TraceEventType.HITL_DECISION,
+      name: "reject",
+      content: "Too risky",
+    });
+
+    renderWithProviders(
+      <ChatMessage message={message} agentName="test-agent" events={[rejectEvent]} />,
+    );
+
+    expect(screen.getByText(/rejected/i)).toBeInTheDocument();
+    expect(screen.getByText(/too risky/i)).toBeInTheDocument();
+  });
 });
diff --git a/tests/unit/components/chat/HITLReviewPanel.test.tsx b/tests/unit/components/chat/HITLReviewPanel.test.tsx
index 0499ac4..5eb1aba 100644
--- a/tests/unit/components/chat/HITLReviewPanel.test.tsx
+++ b/tests/unit/components/chat/HITLReviewPanel.test.tsx
@@ -5,115 +5,164 @@ import { renderWithProviders } from "../../../utils/render";
 import HITLReviewPanel from "@/application/components/chat/HITLReviewPanel";
 import type { ToolCall } from "@/domain/entities/chat/message";
 
-const { mockSendMessageMutate } = vi.hoisted(() => {
+// ─── Mocked useSendMessage (component-level interaction tests) ──────────────
+// The component test mocks useSendMessage to control the mutate fn and to
+// simulate the error state. The invalidate-key contract is validated separately
+// in tests/unit/hooks/chat/useSendMessage.test.tsx against the real hook.
+const { mockSendMessageMutate, mockSendMessageState } = vi.hoisted(() => {
   return {
     mockSendMessageMutate: vi.fn(),
+    mockSendMessageState: {
+      isPending: false,
+      isError: false,
+      error: null as Error | null,
+    },
   };
 });
 
 vi.mock("@/application/hooks/chat/useSendMessage", () => ({
   useSendMessage: () => ({
     mutate: mockSendMessageMutate,
-    isPending: false,
+    isPending: mockSendMessageState.isPending,
+    isError: mockSendMessageState.isError,
+    error: mockSendMessageState.error,
   }),
 }));
 
-const toolCalls: ToolCall[] = [
+// ─── Assumed UI (for the implementer to align) ───────────────────────────────
+// The new multi-tool-call HITLReviewPanel:
+//   - Renders one decision row per tool call, each showing the tool name and
+//     its args, plus per-call Approve / Reject choice controls and (for reject)
+//     an optional reason input.
+//   - Has a single "Submit" button that fires ONE mutation with
+//     `{ decisions: [...] }` covering every tool call.
+//   - For the single-tool-call case the same flow applies (a list of 1); the
+//     Submit button is still used so the payload is always `{ decisions: [...] }`.
+//   - Displays `sendMessage.error` (the error message text) when the mutation
+//     fails, instead of silently swallowing it.
+// The tests below assert the PAYLOAD contract (the `decisions` array shape)
+// rather than precise DOM click sequences; if the implementer chooses slightly
+// different controls (e.g. a per-call select instead of two buttons) the test
+// selectors may need a minor tweak, but the payload assertions are the source
+// of truth.
+
+function resetMockState() {
+  mockSendMessageState.isPending = false;
+  mockSendMessageState.isError = false;
+  mockSendMessageState.error = null;
+}
+
+const singleToolCall: ToolCall[] = [
   {
     id: "tc-1",
-    name: "create_file",
-    args: { path: "/tmp/test.txt", content: "hello" },
+    name: "search",
+    args: { query: "hello" },
   },
 ];
 
+const twoToolCalls: ToolCall[] = [
+  { id: "tc-a", name: "delete", args: { path: "/tmp/a.txt" } },
+  { id: "tc-b", name: "write", args: { path: "/tmp/b.txt", content: "x" } },
+];
+
 describe("HITLReviewPanel", () => {
   beforeEach(() => {
     mockSendMessageMutate.mockClear();
+    resetMockState();
   });
 
-  it("renders tool name in idle state", () => {
-    renderWithProviders(<HITLReviewPanel toolCalls={toolCalls} threadId="thread-123" />);
-
-    expect(screen.getByText("create_file")).toBeInTheDocument();
-  });
-
-  it("shows 'Review Data' button in idle state", () => {
-    renderWithProviders(<HITLReviewPanel toolCalls={toolCalls} threadId="thread-123" />);
+  // ─── Multi-tool-call rendering ─────────────────────────────────────────────
+  it("renders a decision row for each tool call", () => {
+    renderWithProviders(<HITLReviewPanel toolCalls={twoToolCalls} threadId="thread-123" />);
 
-    expect(screen.getByRole("button", { name: /review data/i })).toBeInTheDocument();
+    expect(screen.getByText("delete")).toBeInTheDocument();
+    expect(screen.getByText("write")).toBeInTheDocument();
   });
 
   it("shows validation required text", () => {
-    renderWithProviders(<HITLReviewPanel toolCalls={toolCalls} threadId="thread-123" />);
+    renderWithProviders(<HITLReviewPanel toolCalls={singleToolCall} threadId="thread-123" />);
 
     expect(screen.getByText(/validation required/i)).toBeInTheDocument();
   });
 
-  it("transitions to reviewing state when Review Data is clicked", async () => {
-    const user = userEvent.setup();
-
-    renderWithProviders(<HITLReviewPanel toolCalls={toolCalls} threadId="thread-123" />);
-
-    await user.click(screen.getByRole("button", { name: /review data/i }));
+  it("handles empty tool calls gracefully", () => {
+    renderWithProviders(<HITLReviewPanel toolCalls={[]} threadId="thread-123" />);
 
-    // In reviewing state, Approve and Reject buttons should appear
-    expect(screen.getByRole("button", { name: /approve/i })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: /reject/i })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: /cancel/i })).toBeInTheDocument();
+    expect(screen.getByText("Unknown tool")).toBeInTheDocument();
   });
 
-  it("shows tool args in reviewing state", async () => {
+  // ─── Single tool call: approve ─────────────────────────────────────────────
+  it("single tool call: approve sends a decisions list of 1", async () => {
     const user = userEvent.setup();
 
-    renderWithProviders(<HITLReviewPanel toolCalls={toolCalls} threadId="thread-123" />);
+    renderWithProviders(<HITLReviewPanel toolCalls={singleToolCall} threadId="thread-123" />);
 
+    // Open the review surface (existing "Review Data" entry point is kept).
     await user.click(screen.getByRole("button", { name: /review data/i }));
 
-    expect(screen.getByText(/\/tmp\/test\.txt/)).toBeInTheDocument();
+    // Choose approve for the single call and submit.
+    await user.click(screen.getByRole("button", { name: /approve/i }));
+    await user.click(screen.getByRole("button", { name: /submit/i }));
+
+    expect(mockSendMessageMutate).toHaveBeenCalledWith({
+      decisions: [{ tool_call_id: "tc-1", action: "approve" }],
+    });
   });
 
-  it("calls sendMessage with approve action when Approve is clicked", async () => {
+  // ─── Single tool call: reject with reason ──────────────────────────────────
+  it("reject with reason sends decisions with the reason", async () => {
     const user = userEvent.setup();
 
-    renderWithProviders(<HITLReviewPanel toolCalls={toolCalls} threadId="thread-123" />);
+    renderWithProviders(<HITLReviewPanel toolCalls={singleToolCall} threadId="thread-123" />);
 
     await user.click(screen.getByRole("button", { name: /review data/i }));
-    await user.click(screen.getByRole("button", { name: /approve/i }));
+    await user.click(screen.getByRole("button", { name: /reject/i }));
+
+    const reasonInput = screen.getByPlaceholderText(/reason for rejection/i);
+    await user.type(reasonInput, "Too risky");
+
+    await user.click(screen.getByRole("button", { name: /confirm reject/i }));
 
     expect(mockSendMessageMutate).toHaveBeenCalledWith({
-      tool_call_id: "tc-1",
-      action: "approve",
+      decisions: [{ tool_call_id: "tc-1", action: "reject", reason: "Too risky" }],
     });
   });
 
-  it("transitions to rejecting state on first Reject click", async () => {
+  // ─── Multi tool calls: submit sends all decisions ─────────────────────────
+  it("multi tool calls: submit sends all decisions in one mutation", async () => {
     const user = userEvent.setup();
 
-    renderWithProviders(<HITLReviewPanel toolCalls={toolCalls} threadId="thread-123" />);
+    renderWithProviders(<HITLReviewPanel toolCalls={twoToolCalls} threadId="thread-123" />);
 
     await user.click(screen.getByRole("button", { name: /review data/i }));
-    await user.click(screen.getByRole("button", { name: /^reject$/i }));
 
-    // Should now show "Confirm Reject" and a reason input
-    expect(screen.getByRole("button", { name: /confirm reject/i })).toBeInTheDocument();
-    expect(screen.getByPlaceholderText(/reason for rejection/i)).toBeInTheDocument();
-  });
-
-  it("returns to idle state when Cancel is clicked", async () => {
-    const user = userEvent.setup();
+    // First call: approve.
+    await user.click(screen.getByRole("button", { name: /approve.*delete/i }));
 
-    renderWithProviders(<HITLReviewPanel toolCalls={toolCalls} threadId="thread-123" />);
+    // Second call: reject with a reason.
+    await user.click(screen.getByRole("button", { name: /reject.*write/i }));
+    const reasonInput = screen.getByPlaceholderText(/reason for rejection/i);
+    await user.type(reasonInput, "Unsafe");
 
-    await user.click(screen.getByRole("button", { name: /review data/i }));
-    await user.click(screen.getByRole("button", { name: /cancel/i }));
+    // Single Submit sends both decisions in one payload.
+    await user.click(screen.getByRole("button", { name: /submit/i }));
 
-    // Should be back to idle with "Review Data" button
-    expect(screen.getByRole("button", { name: /review data/i })).toBeInTheDocument();
+    expect(mockSendMessageMutate).toHaveBeenCalledWith({
+      decisions: [
+        { tool_call_id: "tc-a", action: "approve" },
+        { tool_call_id: "tc-b", action: "reject", reason: "Unsafe" },
+      ],
+    });
   });
 
-  it("handles empty tool calls gracefully", () => {
-    renderWithProviders(<HITLReviewPanel toolCalls={[]} threadId="thread-123" />);
+  // ─── Error display (no longer silent) ─────────────────────────────────────
+  it("displays the mutation error when send fails", () => {
+    mockSendMessageState.isError = true;
+    mockSendMessageState.error = new Error("boom");
 
-    expect(screen.getByText("Unknown tool")).toBeInTheDocument();
+    renderWithProviders(<HITLReviewPanel toolCalls={singleToolCall} threadId="thread-123" />);
+
+    // The error message must be visible somewhere in the panel (not swallowed).
+    expect(screen.getByText(/boom/i)).toBeInTheDocument();
   });
-});
+});
\ No newline at end of file
diff --git a/tests/unit/components/chat/MessageList.test.tsx b/tests/unit/components/chat/MessageList.test.tsx
index ee42dc3..d32360f 100644
--- a/tests/unit/components/chat/MessageList.test.tsx
+++ b/tests/unit/components/chat/MessageList.test.tsx
@@ -8,7 +8,7 @@ import {
   createTraceEvent,
   createMessage,
 } from "../../../fixtures/external";
-import { MessageRole } from "@/domain/entities/chat/message";
+import { MessageRole, MessageStatus } from "@/domain/entities/chat/message";
 import { TraceEventType } from "@/domain/entities/chat/traceEvent";
 import { useChatStore } from "@/application/stores/useChatStore";
 
@@ -106,4 +106,71 @@ describe("MessageList", () => {
 
     expect(screen.getByText(/Bold streaming/i)).toBeInTheDocument();
   });
+
+  // ─── HITL refactor: isLast gating (no stale panel on older messages) ──────
+  // Contract: MessageList passes `isLast={idx === entries.length - 1}` to each
+  // ChatMessage rendered from `entries` (NOT for the pending user message or
+  // the streaming message). Combined with ChatMessage's `isLast` gate, an
+  // older awaiting_hitl message must NOT render a HITL panel once the
+  // conversation has continued. We assert via `data-od-id="hitl-panel"`.
+  function hitlPanelCount(container: HTMLElement): number {
+    return container.querySelectorAll('[data-od-id="hitl-panel"]').length;
+  }
+
+  it("renders the HITL panel on the last message when it is awaiting_hitl", () => {
+    mockHistory = createThreadHistory({
+      turns: [
+        createTurn({
+          human_message: createMessage({ role: MessageRole.HUMAN, content: "first" }),
+          ai_message: createMessage({
+            role: MessageRole.AI,
+            content: "needs review",
+            status: MessageStatus.AWAITING_HITL,
+            tool_calls: [{ id: "tc-1", name: "x", args: {} }],
+          }),
+          events: [],
+        }),
+      ],
+    });
+
+    const { container } = renderWithProviders(
+      <MessageList threadId="thread-1" agentName="test-agent" />,
+    );
+
+    expect(hitlPanelCount(container)).toBe(1);
+  });
+
+  it("does NOT render a HITL panel on an earlier awaiting_hitl message when the last is completed", () => {
+    mockHistory = createThreadHistory({
+      turns: [
+        createTurn({
+          human_message: createMessage({ role: MessageRole.HUMAN, content: "first" }),
+          ai_message: createMessage({
+            role: MessageRole.AI,
+            content: "older awaiting",
+            status: MessageStatus.AWAITING_HITL,
+            tool_calls: [{ id: "tc-old", name: "x", args: {} }],
+          }),
+          events: [],
+        }),
+        createTurn({
+          human_message: createMessage({ role: MessageRole.HUMAN, content: "second" }),
+          ai_message: createMessage({
+            role: MessageRole.AI,
+            content: "done",
+            status: MessageStatus.COMPLETED,
+          }),
+          events: [],
+        }),
+      ],
+    });
+
+    const { container } = renderWithProviders(
+      <MessageList threadId="thread-1" agentName="test-agent" />,
+    );
+
+    // The older awaiting_hitl message is NOT the last entry, so its panel must
+    // be suppressed by the isLast gate.
+    expect(hitlPanelCount(container)).toBe(0);
+  });
 });
diff --git a/tests/unit/domain/entities/chat/traceEvent.test.ts b/tests/unit/domain/entities/chat/traceEvent.test.ts
index 11f29d7..2f90385 100644
--- a/tests/unit/domain/entities/chat/traceEvent.test.ts
+++ b/tests/unit/domain/entities/chat/traceEvent.test.ts
@@ -7,7 +7,7 @@ import {
 import { createTraceEvent, createTurn, createThreadHistory } from "../../../../fixtures/external";
 
 describe("TraceEventType", () => {
-  it("exposes the six backend event types", () => {
+  it("exposes the backend event types", () => {
     expect(TraceEventType.HUMAN_MESSAGE).toBe("human_message");
     expect(TraceEventType.AI_MESSAGE).toBe("ai_message");
     expect(TraceEventType.THINKING).toBe("thinking");
@@ -16,8 +16,16 @@ describe("TraceEventType", () => {
     expect(TraceEventType.TOOL_RESULT).toBe("tool_result");
   });
 
-  it("has exactly six enum members", () => {
-    expect(Object.keys(TraceEventType)).toHaveLength(6);
+  // ─── HITL refactor: new HITL_DECISION event type ─────────────────────────
+  // Contract: a new enum member `HITL_DECISION = "hitl_decision"` is added so
+  // that chatApi's `Object.values(TraceEventType)`-driven VALID_EVENT_TYPES
+  // accepts HITL decision trace events streamed from the backend.
+  it("exposes the HITL_DECISION event type", () => {
+    expect(TraceEventType.HITL_DECISION).toBe("hitl_decision");
+  });
+
+  it("has exactly seven enum members", () => {
+    expect(Object.keys(TraceEventType)).toHaveLength(7);
   });
 });
 
@@ -85,6 +93,7 @@ describe("Message turn_id field", () => {
       [TraceEventType.CONTENT]: ev,
       [TraceEventType.TOOL_CALL]: ev,
       [TraceEventType.TOOL_RESULT]: ev,
+      [TraceEventType.HITL_DECISION]: ev,
     };
     expect(byType[TraceEventType.TOOL_CALL]).toBe(ev);
   });
diff --git a/tests/unit/hooks/chat/useSendMessage.test.tsx b/tests/unit/hooks/chat/useSendMessage.test.tsx
index cb12cbd..d94368e 100644
--- a/tests/unit/hooks/chat/useSendMessage.test.tsx
+++ b/tests/unit/hooks/chat/useSendMessage.test.tsx
@@ -74,7 +74,11 @@ describe("useSendMessage", () => {
     expect(result.current.error?.message).toBe("Cannot send message without an active thread");
   });
 
-  it("invalidates messages query on success", async () => {
+  // ─── HITL refactor: invalidation key fix ───────────────────────────────────
+  // The message list is driven by `useThreadHistory` whose query key is
+  // `["history", threadId]`. The hook MUST invalidate that key (not the legacy
+  // `["messages", threadId]`) so the UI refreshes after an approve/reject.
+  it("invalidates the ['history', threadId] query on success", async () => {
     const mockResponse = createMessage({
       role: MessageRole.AI,
       content: "Response",
@@ -93,7 +97,65 @@ describe("useSendMessage", () => {
 
     await waitFor(() => expect(result.current.isSuccess).toBe(true));
     expect(invalidateSpy).toHaveBeenCalledWith({
+      queryKey: ["history", "thread-123"],
+    });
+  });
+
+  it("does NOT invalidate the legacy ['messages', threadId] query", async () => {
+    const mockResponse = createMessage({
+      role: MessageRole.AI,
+      content: "Response",
+    });
+    vi.mocked(chatApi.sendMessage).mockResolvedValue(mockResponse);
+    const { wrapper, queryClient } = createWrapper();
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+
+    const { result } = renderHook(() => useSendMessage("thread-123"), {
+      wrapper,
+    });
+
+    act(() => {
+      result.current.mutate({ message: "Hello" });
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    // The old (buggy) key must no longer be invalidated.
+    expect(invalidateSpy).not.toHaveBeenCalledWith({
       queryKey: ["messages", "thread-123"],
     });
   });
-});
+
+  // ─── HITL refactor: multi-decision payload ─────────────────────────────────
+  // Contract: when the caller passes a `decisions` array, the hook forwards it
+  // verbatim to chatApi.sendMessage (preferred multi-decision payload).
+  it("sends the decisions payload to chatApi.sendMessage", async () => {
+    const mockResponse = createMessage({
+      role: MessageRole.AI,
+      content: "Done",
+    });
+    vi.mocked(chatApi.sendMessage).mockResolvedValue(mockResponse);
+    const { wrapper } = createWrapper();
+
+    const { result } = renderHook(() => useSendMessage("thread-123"), {
+      wrapper,
+    });
+
+    const decisions = [
+      { tool_call_id: "tc-1", action: "approve" as const },
+      { tool_call_id: "tc-2", action: "reject" as const, reason: "Too risky" },
+    ];
+
+    act(() => {
+      result.current.mutate({ decisions });
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(chatApi.sendMessage).toHaveBeenCalledWith("thread-123", {
+      decisions: [
+        { tool_call_id: "tc-1", action: "approve" },
+        { tool_call_id: "tc-2", action: "reject", reason: "Too risky" },
+      ],
+    });
+  });
+});
\ No newline at end of file