From 068acd735531aca6fe012bffe35853812695fe3f Mon Sep 17 00:00:00 2001
From: morgmart <98432065+morgmart@users.noreply.github.com>
Date: Mon, 17 Aug 2026 14:43:19 -0700
Subject: [PATCH 1/2] fix(chat): keep agent work expansions anchored

---
 src/features/chat/ui/AgentWorkPanel.tsx       | 15 +++++-
 src/features/chat/ui/ToolCallAdapter.tsx      |  5 +-
 .../chat/ui/VirtualMessageTimeline.tsx        |  7 ++-
 .../ui/__tests__/ToolCallAdapter.test.tsx     | 19 ++++++++
 .../__tests__/VirtualMessageTimeline.test.tsx | 48 +++++++++++++++++++
 5 files changed, 90 insertions(+), 4 deletions(-)

diff --git a/src/features/chat/ui/AgentWorkPanel.tsx b/src/features/chat/ui/AgentWorkPanel.tsx
index 50feea638..02753e708 100644
--- a/src/features/chat/ui/AgentWorkPanel.tsx
+++ b/src/features/chat/ui/AgentWorkPanel.tsx
@@ -27,6 +27,7 @@ import type {
   ToolCallStatus,
 } from "@/shared/types/messages";
 import type { TranscriptAgentWorkPayload } from "@/features/chat/transcript/projection/transcriptItemTypes";
+import { useTranscriptRowStateAdapter } from "@/features/chat/transcript/row-state";
 import { ToolCallAdapter } from "./ToolCallAdapter";
 
 interface ToolTimelineItem {
@@ -351,6 +352,7 @@ export function AgentWorkPanel({
 }) {
   const { t } = useTranslation("chat");
   const prefersReducedMotion = useReducedMotion();
+  const { markRowInteracted, pinScrollAnchor } = useTranscriptRowStateAdapter();
   const items = useMemo(
     () => buildAgentWorkTimeline(payload.content),
     [payload.content],
@@ -423,7 +425,12 @@ export function AgentWorkPanel({
   return (
     <Collapsible
       open={open}
-      onOpenChange={setOpen}
+      onOpenChange={(nextOpen) => {
+        markRowInteracted("agent-work-disclosure");
+        pinScrollAnchor();
+        setOpen(nextOpen);
+      }}
+      data-role="agent-work-panel"
       className="mt-3 w-full min-w-0 max-w-full"
     >
       <div>
@@ -484,7 +491,11 @@ export function AgentWorkPanel({
               >
                 <Collapsible
                   open={previousStepsOpen}
-                  onOpenChange={setPreviousStepsOpen}
+                  onOpenChange={(nextOpen) => {
+                    markRowInteracted("agent-work-previous-steps");
+                    pinScrollAnchor();
+                    setPreviousStepsOpen(nextOpen);
+                  }}
                 >
                   <CollapsibleTrigger asChild>
                     <Button
diff --git a/src/features/chat/ui/ToolCallAdapter.tsx b/src/features/chat/ui/ToolCallAdapter.tsx
index 500bea55b..ce743bc30 100644
--- a/src/features/chat/ui/ToolCallAdapter.tsx
+++ b/src/features/chat/ui/ToolCallAdapter.tsx
@@ -593,7 +593,10 @@ export function ToolCallAdapter({
           className="text-muted-foreground [&_button]:text-muted-foreground [&_code]:text-muted-foreground [&_dd]:text-muted-foreground [&_dt]:text-muted-foreground [&_span]:text-muted-foreground"
         >
           {agentWorkLayout ? (
-            <div className="space-y-3 py-1">
+            <div
+              data-role="agent-work-tool-details"
+              className="max-h-48 space-y-3 overflow-y-auto overscroll-contain py-1"
+            >
               <AgentWorkToolSection
                 label={t("tools.inputSummary.command")}
                 value={commandRow?.value ?? null}
diff --git a/src/features/chat/ui/VirtualMessageTimeline.tsx b/src/features/chat/ui/VirtualMessageTimeline.tsx
index 1e11eb9b2..facc6fd49 100644
--- a/src/features/chat/ui/VirtualMessageTimeline.tsx
+++ b/src/features/chat/ui/VirtualMessageTimeline.tsx
@@ -3799,7 +3799,11 @@ function VirtualMessageTimelineSession({
     ) {
       return;
     }
-    if (resolvedScrollTargetMessageId || userDetachedRef.current) {
+    if (
+      resolvedScrollTargetMessageId ||
+      userDetachedRef.current ||
+      virtualTimelineSnapshot.controllerState.anchor.type !== "bottom"
+    ) {
       return;
     }
     requestBottomScroll();
@@ -3809,6 +3813,7 @@ function VirtualMessageTimelineSession({
     requestBottomScroll,
     resolvedScrollTargetMessageId,
     streamingMessageId,
+    virtualTimelineSnapshot.controllerState.anchor.type,
   ]);
 
   const messageList = (
diff --git a/src/features/chat/ui/__tests__/ToolCallAdapter.test.tsx b/src/features/chat/ui/__tests__/ToolCallAdapter.test.tsx
index 6d724f5e1..aef8603e6 100644
--- a/src/features/chat/ui/__tests__/ToolCallAdapter.test.tsx
+++ b/src/features/chat/ui/__tests__/ToolCallAdapter.test.tsx
@@ -409,6 +409,25 @@ describe("ToolCallAdapter — expanded body", () => {
     renderAdapter({ open: true, isError: true, result: "Boom" });
     expect(screen.getByText("Boom")).toHaveClass("text-destructive");
   });
+
+  it("caps and scrolls an inner details viewport in the agent work layout", () => {
+    const { container } = renderAdapter({ open: true, agentWorkLayout: true });
+
+    expect(
+      container.querySelector('[data-role="agent-work-tool-details"]'),
+    ).toHaveClass("max-h-48", "overflow-y-auto", "overscroll-contain");
+    expect(
+      container.querySelector('[data-role="tool-call-content"]'),
+    ).not.toHaveClass("max-h-48", "overflow-y-auto");
+  });
+
+  it("does not add a capped details viewport outside the agent work layout", () => {
+    const { container } = renderAdapter({ open: true });
+
+    expect(
+      container.querySelector('[data-role="agent-work-tool-details"]'),
+    ).not.toBeInTheDocument();
+  });
 });
 
 describe("ToolCallAdapter — text + structured de-dupe matrix", () => {
diff --git a/src/features/chat/ui/__tests__/VirtualMessageTimeline.test.tsx b/src/features/chat/ui/__tests__/VirtualMessageTimeline.test.tsx
index d74669d21..3bda8c152 100644
--- a/src/features/chat/ui/__tests__/VirtualMessageTimeline.test.tsx
+++ b/src/features/chat/ui/__tests__/VirtualMessageTimeline.test.tsx
@@ -1104,6 +1104,54 @@ describe("VirtualMessageTimeline", () => {
     expect(screen.queryByTestId("message-assistant-work:answer")).toBeNull();
   });
 
+  it("keeps a revealed agent-work row anchored as its measured height grows", () => {
+    mockTranscriptElementMeasurements();
+    const animationFrame = mockRequestAnimationFrame();
+    const assistant: Message = {
+      id: "assistant-work",
+      role: "assistant",
+      created: Date.UTC(2026, 5, 4, 12, 1, 0),
+      metadata: { userVisible: true },
+      content: [
+        { type: "thinking", text: "Planning" },
+        {
+          type: "toolRequest",
+          id: "tool-1",
+          name: "scan",
+          arguments: {},
+          status: "completed",
+        },
+        { type: "text", text: "Final answer" },
+      ],
+    };
+    renderWithProviders(
+      <VirtualMessageTimeline sessionId="session-1" messages={[assistant]} />,
+    );
+    const scroller = screen.getByTestId("message-timeline-scroll");
+    const scrollTo = attachScrollTo(scroller);
+    setScrollMetrics(scroller, {
+      scrollTop: 500,
+      scrollHeight: 1000,
+      clientHeight: 500,
+    });
+    animationFrame.runAll(0);
+    scrollTo.mockClear();
+
+    fireEvent.click(screen.getByRole("button", { name: /previous steps?/ }));
+    animationFrame.runAll(100);
+    scrollTo.mockClear();
+
+    const agentWorkRow = screen.getByTestId(
+      "virtual-transcript-row-message:assistant-work:agent-work",
+    );
+    agentWorkRow.setAttribute("data-mock-row-height", "480");
+    triggerResizeObservers();
+    animationFrame.runAll(200);
+
+    expect(scroller.scrollTop).toBe(500);
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+
   it("mounts a just-settled agent-work row open before collapsing", async () => {
     const animationFrame = mockRequestAnimationFrame();
     const user = textMessage("user-1", "user", "Please inspect");

From adc4c1d5c70939f29e819fcbae3d1fda4180d204 Mon Sep 17 00:00:00 2001
From: morgmart <98432065+morgmart@users.noreply.github.com>
Date: Mon, 17 Aug 2026 15:01:51 -0700
Subject: [PATCH 2/2] fix(chat): make tool details keyboard scrollable

---
 src/features/chat/ui/ToolCallAdapter.tsx      |  6 ++++--
 .../ui/__tests__/ToolCallAdapter.test.tsx     | 10 +++++++---
 src/shared/i18n/locales/en/chat.json          |  1 +
 src/shared/i18n/locales/es/chat.json          |  1 +
 src/shared/ui/ai-elements/tool.tsx            | 19 +++++++++++++++++++
 5 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/src/features/chat/ui/ToolCallAdapter.tsx b/src/features/chat/ui/ToolCallAdapter.tsx
index ce743bc30..fca416885 100644
--- a/src/features/chat/ui/ToolCallAdapter.tsx
+++ b/src/features/chat/ui/ToolCallAdapter.tsx
@@ -8,6 +8,7 @@ import { CodeBlock } from "@/shared/ui/ai-elements/code-block";
 import {
   Tool,
   ToolContent,
+  ToolDetailsViewport,
   ToolHeader,
   ToolInput,
   ToolOutput,
@@ -593,8 +594,9 @@ export function ToolCallAdapter({
           className="text-muted-foreground [&_button]:text-muted-foreground [&_code]:text-muted-foreground [&_dd]:text-muted-foreground [&_dt]:text-muted-foreground [&_span]:text-muted-foreground"
         >
           {agentWorkLayout ? (
-            <div
+            <ToolDetailsViewport
               data-role="agent-work-tool-details"
+              aria-label={t("tools.details")}
               className="max-h-48 space-y-3 overflow-y-auto overscroll-contain py-1"
             >
               <AgentWorkToolSection
@@ -614,7 +616,7 @@ export function ToolCallAdapter({
                 label={t("tools.structuredContent")}
                 value={structuredDetails}
               />
-            </div>
+            </ToolDetailsViewport>
           ) : showCombinedSurface ? (
             <ToolSurface tone="muted" className="bg-muted">
               <ToolInput
diff --git a/src/features/chat/ui/__tests__/ToolCallAdapter.test.tsx b/src/features/chat/ui/__tests__/ToolCallAdapter.test.tsx
index aef8603e6..fe63e4beb 100644
--- a/src/features/chat/ui/__tests__/ToolCallAdapter.test.tsx
+++ b/src/features/chat/ui/__tests__/ToolCallAdapter.test.tsx
@@ -413,9 +413,13 @@ describe("ToolCallAdapter — expanded body", () => {
   it("caps and scrolls an inner details viewport in the agent work layout", () => {
     const { container } = renderAdapter({ open: true, agentWorkLayout: true });
 
-    expect(
-      container.querySelector('[data-role="agent-work-tool-details"]'),
-    ).toHaveClass("max-h-48", "overflow-y-auto", "overscroll-contain");
+    const details = screen.getByRole("region", { name: "Tool details" });
+    expect(details).toHaveAttribute("tabindex", "0");
+    expect(details).toHaveClass(
+      "max-h-48",
+      "overflow-y-auto",
+      "overscroll-contain",
+    );
     expect(
       container.querySelector('[data-role="tool-call-content"]'),
     ).not.toHaveClass("max-h-48", "overflow-y-auto");
diff --git a/src/shared/i18n/locales/en/chat.json b/src/shared/i18n/locales/en/chat.json
index 657a65a81..aa4d49ffa 100644
--- a/src/shared/i18n/locales/en/chat.json
+++ b/src/shared/i18n/locales/en/chat.json
@@ -547,6 +547,7 @@
   },
   "tools": {
     "content": "Content",
+    "details": "Tool details",
     "error": "Error",
     "input": "Input",
     "result": "Result",
diff --git a/src/shared/i18n/locales/es/chat.json b/src/shared/i18n/locales/es/chat.json
index 2b28b451b..65f824346 100644
--- a/src/shared/i18n/locales/es/chat.json
+++ b/src/shared/i18n/locales/es/chat.json
@@ -544,6 +544,7 @@
   },
   "tools": {
     "content": "Contenido",
+    "details": "Detalles de la herramienta",
     "error": "Error",
     "input": "Entrada",
     "result": "Resultado",
diff --git a/src/shared/ui/ai-elements/tool.tsx b/src/shared/ui/ai-elements/tool.tsx
index 76cbf3b0c..789df8e36 100644
--- a/src/shared/ui/ai-elements/tool.tsx
+++ b/src/shared/ui/ai-elements/tool.tsx
@@ -256,6 +256,25 @@ export const ToolContent = ({ className, ...props }: ToolContentProps) => (
   />
 );
 
+export type ToolDetailsViewportProps = ComponentProps<"div">;
+
+export const ToolDetailsViewport = ({
+  className,
+  ...props
+}: ToolDetailsViewportProps) => (
+  // Scrollable regions need a tab stop so keyboard users can operate them.
+  <div
+    role="region"
+    // biome-ignore lint/a11y/noNoninteractiveTabindex: focus transfers keyboard scrolling to this overflow viewport.
+    tabIndex={0}
+    className={cn(
+      "rounded-sm outline-none transition-[color,box-shadow] focus-visible:ring-1 focus-visible:ring-ring/50",
+      className,
+    )}
+    {...props}
+  />
+);
+
 export type ToolSectionProps = ComponentProps<"div"> & {
   label: string;
 };