gemini-cli - 💡(How to fix) Fix [Bug] Race condition in HookSystemMessage rendering causes UI layout inconsistency [1 participants]

Description

There is a race condition in how HookSystemMessage events (emitted by hooks like StopHook) are rendered in the CLI. If a hook emits a message while the assistant still has pending response content (streaming or buffering), the message is immediately injected into the chat history. This causes the hook's feedback to appear out of order, often interleaved with or preceding the final response block.

Reproduction

1. Use a hook (e.g., StopHook) that emits a HookSystemMessage at the end of a tool call or response.
2. Observe that the message sometimes appears in the middle of the assistant's response if the response hasn't been fully committed to history yet.

Root Cause

In interactiveCli, the handleHookSystemMessage handler calls historyManager.addItem immediately. It does not wait for the assistant's current turn to finish (i.e., it doesn't check pendingHistoryItems).

Proposed Fix

Implement a queuing mechanism to defer hook system messages until the assistant's response is complete.

1. Create a queuedHookSystemMessagesRef to store messages.
2. In handleHookSystemMessage, check if pendingHistoryItems.length > 0. If so, push to the queue.
3. Use a useEffect monitoring pendingHistoryItems to flush the queue when it becomes empty.

Reference Implementation:

const queuedHookSystemMessagesRef = useRef([]);
const flushQueuedHookSystemMessages = useCallback(() => {
  if (queuedHookSystemMessagesRef.current.length === 0) return;
  const queuedMessages = queuedHookSystemMessagesRef.current;
  queuedHookSystemMessagesRef.current = [];
  for (const payload of queuedMessages) {
    historyManager.addItem(
      {
        type: "info",
        text: payload.message,
        source: payload.hookName
      },
      Date.now()
    );
  }
}, [historyManager]);

useEffect(() => {
  if (pendingHistoryItems.length === 0) {
    flushQueuedHookSystemMessages();
  }
}, [pendingHistoryItems, flushQueuedHookSystemMessages]);

const handleHookSystemMessage = (payload) => {
  if (pendingHistoryItems.length > 0) {
    queuedHookSystemMessagesRef.current.push(payload);
    return;
  }
  historyManager.addItem(
    {
      type: "info",
      text: payload.message,
      source: payload.hookName
    },
    Date.now()
  );
};