feat(react): lookup pending decision by id

Author: marslavish

packages/react/README.md

@@ -12,3 +12,10 @@ Currently exposes a single hook:
 The hook ships no UI. State lives in messages — there is no separate run
 store, no `runId`. Resumption after a tool decision re-POSTs to the same `api`
 endpoint with the augmented message log.
+
+`respondWithDecision(toolCallId, value)` walks `messages` backwards to find
+the most recent assistant message that owns a `toolCall` block matching
+`toolCallId` with no decision attached, mutates that block, and re-POSTs.
+This means callers can append messages (system notes, status writes, etc.)
+to the log between the pause and the user's response — the lookup is by id,
+not position. Throws if no matching pending decision is found.

packages/react/__tests__/use-chat.test.ts

@@ -335,6 +335,109 @@ describe('useChat', () => {
       expect(result.current.pendingDecision).toBeUndefined();
       expect(result.current.isStreaming).toBe(false);
     });
+
+    it('finds the pending assistant by toolCallId when a later message was appended', async () => {
+      // Simulates the queue-based architecture: a system note (modelled as a
+      // user-role message) lands after the pause, so the trailing message is
+      // not the assistant carrying the pending tool call.
+      const assistantWithToolCall = makeAssistantWithToolCall();
+      const trailingNote = makeUser('queued note arrived after pause', 99);
+      const initial: Message[] = [
+        makeUser('hi'),
+        assistantWithToolCall,
+        trailingNote,
+      ];
+      const fetchFn = jest.fn(
+        async (_url: RequestInfo | URL, _init?: RequestInit): Promise<Response> =>
+          streamFromEvents([
+            { type: 'agent_start' },
+            { type: 'agent_end', messages: initial },
+          ])
+      );
+
+      const { result } = renderHook(() =>
+        useChat({ api: '/chat', fetch: fetchFn, initialMessages: initial })
+      );
+
+      await act(async () => {
+        await result.current.respondWithDecision('call_1', 'allow');
+      });
+
+      const sent = JSON.parse(fetchFn.mock.calls[0][1]!.body as string);
+      expect(sent.messages).toHaveLength(3);
+      expect(sent.messages[1].content[0]).toMatchObject({
+        type: 'toolCall',
+        id: 'call_1',
+        decision: 'allow',
+      });
+      // Trailing note is preserved in its position.
+      expect(sent.messages[2]).toMatchObject({ role: 'user', content: 'queued note arrived after pause' });
+    });
+
+    it('throws when no assistant has a pending decision for the toolCallId', async () => {
+      const { result } = renderHook(() => useChat({ api: '/chat' }));
+
+      await expect(
+        act(async () => {
+          await result.current.respondWithDecision('call_unknown', 'allow');
+        })
+      ).rejects.toThrow(/No pending decision for toolCallId 'call_unknown'/);
+    });
+
+    it('skips assistants whose matching toolCall already has a decision', async () => {
+      // Two assistants with different pending toolCallIds. Only the second
+      // matches; the first should be ignored even though it has a decision
+      // already attached for its own (unrelated) call.
+      const earlierWithResolvedDecision = makeFakeAssistantMessage({
+        stopReason: 'toolUse',
+        content: [
+          {
+            type: 'toolCall',
+            id: 'call_resolved',
+            name: 'echo',
+            arguments: { text: 'first' },
+            rawArguments: '{"text":"first"}',
+            decision: 'allow',
+          },
+        ],
+      });
+      const laterPending = makeAssistantWithToolCall();
+      const initial: Message[] = [
+        makeUser('first'),
+        earlierWithResolvedDecision,
+        makeUser('second'),
+        laterPending,
+      ];
+      const fetchFn = jest.fn(
+        async (_url: RequestInfo | URL, _init?: RequestInit): Promise<Response> =>
+          streamFromEvents([
+            { type: 'agent_start' },
+            { type: 'agent_end', messages: initial },
+          ])
+      );
+
+      const { result } = renderHook(() =>
+        useChat({ api: '/chat', fetch: fetchFn, initialMessages: initial })
+      );
+
+      await act(async () => {
+        await result.current.respondWithDecision('call_1', 'allow');
+      });
+
+      const sent = JSON.parse(fetchFn.mock.calls[0][1]!.body as string);
+      // Earlier assistant's already-resolved decision is untouched.
+      expect(sent.messages[1].content[0]).toMatchObject({
+        type: 'toolCall',
+        id: 'call_resolved',
+        decision: 'allow',
+      });
+      // Later assistant's matching call gets the new decision.
+      expect(sent.messages[3].content[0]).toMatchObject({
+        type: 'toolCall',
+        id: 'call_1',
+        decision: 'allow',
+      });
+    });
   });
 
   describe('error handling', () => {

packages/react/src/use-chat.ts

@@ -191,24 +191,38 @@ export function useChat(options: UseChatOptions): UseChatResult {
   const respondWithDecision = useCallback(
     async (toolCallId: string, value: unknown): Promise<void> => {
       const current = messagesRef.current;
-      if (current.length === 0) {
-        throw new Error('No messages to attach a decision to');
+      let targetIdx = -1;
+      for (let i = current.length - 1; i >= 0; i--) {
+        const msg = current[i];
+        if (msg.role !== 'assistant') continue;
+        const match = msg.content.find(
+          (block) => block.type === 'toolCall' && block.id === toolCallId
+        );
+        if (!match) continue;
+        if ('decision' in match && match.decision !== undefined) continue;
+        targetIdx = i;
+        break;
       }
-      const lastIdx = current.length - 1;
-      const last = current[lastIdx];
-      if (last.role !== 'assistant') {
-        throw new Error('Last message is not an assistant message; cannot attach a decision');
+      if (targetIdx === -1) {
+        throw new Error(
+          `No pending decision for toolCallId '${toolCallId}'`
+        );
       }
+      const target = current[targetIdx] as AssistantMessage;
       const updatedAssistant: AssistantMessage = {
-        ...last,
-        content: last.content.map((block) => {
+        ...target,
+        content: target.content.map((block) => {
           if (block.type !== 'toolCall' || block.id !== toolCallId) {
             return block;
           }
           return { ...block, decision: value };
         }),
       };
-      const requestMessages = [...current.slice(0, lastIdx), updatedAssistant];
+      const requestMessages = [
+        ...current.slice(0, targetIdx),
+        updatedAssistant,
+        ...current.slice(targetIdx + 1),
+      ];
       setMessages(requestMessages);
       messagesRef.current = requestMessages;
       setPendingDecision(undefined);