feat(ai): allow typing and message queuing during AI streaming

Keep the textarea enabled while AI is responding so users can type
a follow-up clarification mid-turn. Queued messages are injected into
Claude's context via tool response hints and a new getUserClarification
MCP tool, letting Claude incorporate feedback naturally without waiting
for the turn to end.

- Add queueClarification/getAndClearClarification/clearClarification
  node endpoints with image support
- Add getUserClarification MCP tool and clarification hints on all
  tool responses (both hook-based and MCP)
- Static queue bubble above input area with Edit button
- Auto-send queued message as next turn if not consumed mid-turn
- Show consumed clarification as user message bubble in chat

Author: abose

docs/API-Reference/command/Commands.md

@@ -992,7 +992,7 @@ Performs a mixed reset
 ## CMD\_GIT\_TOGGLE\_PANEL
 Toggles the git panel
 
-**Kind**: global variable
+**Kind**: global variable  
 <a name="CMD_CUSTOM_SNIPPETS_PANEL"></a>
 
 ## CMD\_CUSTOM\_SNIPPETS\_PANEL

docs/API-Reference/document/Document.md

@@ -248,7 +248,7 @@ Given a character index within the document text (assuming \n newlines),
 returns the corresponding {line, ch} position. Works whether or not
 a master editor is attached.
 
-**Kind**: instance method of [<code>Document</code>](#Document)
+**Kind**: instance method of [<code>Document</code>](#Document)  
 
 | Param | Type | Description |
 | --- | --- | --- |

docs/API-Reference/view/PanelView.md

@@ -93,7 +93,7 @@ Sets the panel's visibility state
 ### panel.setTitle(newTitle)
 Updates the display title shown in the tab bar for this panel.
 
-**Kind**: instance method of [<code>Panel</code>](#Panel)
+**Kind**: instance method of [<code>Panel</code>](#Panel)  
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -105,7 +105,7 @@ Updates the display title shown in the tab bar for this panel.
 Destroys the panel, removing it from the tab bar, internal maps, and the DOM.
 After calling this, the Panel instance should not be reused.
 
-**Kind**: instance method of [<code>Panel</code>](#Panel)
+**Kind**: instance method of [<code>Panel</code>](#Panel)  
 <a name="Panel+getPanelType"></a>
 
 ### panel.getPanelType() ⇒ <code>string</code>
@@ -117,37 +117,61 @@ gets the Panel's type
 ## \_panelMap : <code>Object.&lt;string, Panel&gt;</code>
 Maps panel ID to Panel instance
 
-**Kind**: global variable
+**Kind**: global variable  
 <a name="_$container"></a>
 
 ## \_$container : <code>jQueryObject</code>
 The single container wrapping all bottom panels
 
-**Kind**: global variable
+**Kind**: global variable  
 <a name="_$tabBar"></a>
 
 ## \_$tabBar : <code>jQueryObject</code>
 The tab bar inside the container
 
-**Kind**: global variable
+**Kind**: global variable  
 <a name="_$tabsOverflow"></a>
 
 ## \_$tabsOverflow : <code>jQueryObject</code>
 Scrollable area holding the tab elements
 
-**Kind**: global variable
+**Kind**: global variable  
 <a name="_openIds"></a>
 
 ## \_openIds : <code>Array.&lt;string&gt;</code>
 Ordered list of currently open (tabbed) panel IDs
 
-**Kind**: global variable
+**Kind**: global variable  
 <a name="_activeId"></a>
 
 ## \_activeId : <code>string</code> \| <code>null</code>
 The panel ID of the currently visible (active) tab
 
-**Kind**: global variable
+**Kind**: global variable  
+<a name="_isMaximized"></a>
+
+## \_isMaximized : <code>boolean</code>
+Whether the bottom panel is currently maximized
+
+**Kind**: global variable  
+<a name="_preMaximizeHeight"></a>
+
+## \_preMaximizeHeight : <code>number</code> \| <code>null</code>
+The panel height before maximize, for restore
+
+**Kind**: global variable  
+<a name="_$editorHolder"></a>
+
+## \_$editorHolder : <code>jQueryObject</code>
+The editor holder element, passed from WorkspaceManager
+
+**Kind**: global variable  
+<a name="_recomputeLayout"></a>
+
+## \_recomputeLayout : <code>function</code>
+recomputeLayout callback from WorkspaceManager
+
+**Kind**: global variable  
 <a name="EVENT_PANEL_HIDDEN"></a>
 
 ## EVENT\_PANEL\_HIDDEN : <code>string</code>
@@ -165,31 +189,80 @@ Event when panel is shown
 ## PANEL\_TYPE\_BOTTOM\_PANEL : <code>string</code>
 type for bottom panel
 
+**Kind**: global constant  
+<a name="MAXIMIZE_THRESHOLD"></a>
+
+## MAXIMIZE\_THRESHOLD : <code>number</code>
+Pixel threshold for detecting near-maximize state during resize.
+If the editor holder height is within this many pixels of zero, the
+panel is treated as maximized. Keeps the maximize icon responsive
+during drag without being overly sensitive.
+
+**Kind**: global constant  
+<a name="MIN_PANEL_HEIGHT"></a>
+
+## MIN\_PANEL\_HEIGHT : <code>number</code>
+Minimum panel height (matches Resizer minSize) used as a floor
+when computing a sensible restore height.
+
 **Kind**: global constant  
 <a name="init"></a>
 
-## init($container, $tabBar, $tabsOverflow)
+## init($container, $tabBar, $tabsOverflow, $editorHolder, recomputeLayoutFn)
 Initializes the PanelView module with references to the bottom panel container DOM elements.
 Called by WorkspaceManager during htmlReady.
 
-**Kind**: global function
+**Kind**: global function  
 
 | Param | Type | Description |
 | --- | --- | --- |
 | $container | <code>jQueryObject</code> | The bottom panel container element. |
 | $tabBar | <code>jQueryObject</code> | The tab bar element inside the container. |
 | $tabsOverflow | <code>jQueryObject</code> | The scrollable area holding tab elements. |
+| $editorHolder | <code>jQueryObject</code> | The editor holder element (for maximize height calculation). |
+| recomputeLayoutFn | <code>function</code> | Callback to trigger workspace layout recomputation. |
+
+<a name="exitMaximizeOnResize"></a>
+
+## exitMaximizeOnResize()
+Exit maximize state without resizing (for external callers like drag-resize).
+Clears internal maximize state and resets the button icon.
+
+**Kind**: global function  
+<a name="enterMaximizeOnResize"></a>
+
+## enterMaximizeOnResize()
+Enter maximize state during a drag-resize that reaches the maximum
+height. No pre-maximize height is stored because the user arrived
+here via continuous dragging; a sensible default will be computed if
+they later click the Restore button.
+
+**Kind**: global function  
+<a name="restoreIfMaximized"></a>
+
+## restoreIfMaximized()
+Restore the container's CSS height to the pre-maximize value and clear maximize state.
+Must be called BEFORE Resizer.hide() so the Resizer reads the correct height.
+If not maximized, this is a no-op.
+When the saved height is near-max or unknown, a sensible default is used.
+
+**Kind**: global function  
+<a name="isMaximized"></a>
+
+## isMaximized() ⇒ <code>boolean</code>
+Returns true if the bottom panel is currently maximized.
 
+**Kind**: global function  
 <a name="getOpenBottomPanelIDs"></a>
 
 ## getOpenBottomPanelIDs() ⇒ <code>Array.&lt;string&gt;</code>
 Returns a copy of the currently open bottom panel IDs in tab order.
 
-**Kind**: global function
+**Kind**: global function  
 <a name="hideAllOpenPanels"></a>
 
 ## hideAllOpenPanels() ⇒ <code>Array.&lt;string&gt;</code>
 Hides every open bottom panel tab in a single batch
 
-**Kind**: global function
-**Returns**: <code>Array.&lt;string&gt;</code> - The IDs of panels that were open (useful for restoring later).
+**Kind**: global function  
+**Returns**: <code>Array.&lt;string&gt;</code> - The IDs of panels that were open (useful for restoring later).  

docs/API-Reference/view/WorkspaceManager.md

@@ -56,19 +56,19 @@ Constant representing the type of plugin panel
 ### view/WorkspaceManager.$bottomPanelContainer : <code>jQueryObject</code>
 The single container wrapping all bottom panels
 
-**Kind**: inner property of [<code>view/WorkspaceManager</code>](#module_view/WorkspaceManager)
+**Kind**: inner property of [<code>view/WorkspaceManager</code>](#module_view/WorkspaceManager)  
 <a name="module_view/WorkspaceManager..$statusBarPanelToggle"></a>
 
 ### view/WorkspaceManager.$statusBarPanelToggle : <code>jQueryObject</code>
 Chevron toggle in the status bar
 
-**Kind**: inner property of [<code>view/WorkspaceManager</code>](#module_view/WorkspaceManager)
+**Kind**: inner property of [<code>view/WorkspaceManager</code>](#module_view/WorkspaceManager)  
 <a name="module_view/WorkspaceManager.._statusBarToggleInProgress"></a>
 
 ### view/WorkspaceManager.\_statusBarToggleInProgress : <code>boolean</code>
 True while the status bar toggle button is handling a click
 
-**Kind**: inner property of [<code>view/WorkspaceManager</code>](#module_view/WorkspaceManager)
+**Kind**: inner property of [<code>view/WorkspaceManager</code>](#module_view/WorkspaceManager)  
 <a name="module_view/WorkspaceManager..EVENT_WORKSPACE_UPDATE_LAYOUT"></a>
 
 ### view/WorkspaceManager.EVENT\_WORKSPACE\_UPDATE\_LAYOUT
@@ -108,7 +108,7 @@ The panel's size & visibility are automatically saved & restored as a view-state
 Destroys a bottom panel, removing it from internal registries, the tab bar, and the DOM.
 After calling this, the panel ID is no longer valid and the Panel instance should not be reused.
 
-**Kind**: inner method of [<code>view/WorkspaceManager</code>](#module_view/WorkspaceManager)
+**Kind**: inner method of [<code>view/WorkspaceManager</code>](#module_view/WorkspaceManager)  
 
 | Param | Type | Description |
 | --- | --- | --- |

src-node/claude-code-agent.js

@@ -32,6 +32,10 @@ const { createEditorMcpServer } = require("./mcp-editor-tools");
 
 const CONNECTOR_ID = "ph_ai_claude";
 
+const CLARIFICATION_HINT =
+    " IMPORTANT: The user has typed a follow-up clarification while you were working." +
+    " Call the getUserClarification tool to read it before proceeding.";
+
 // Lazy-loaded ESM module reference
 let queryModule = null;
 
@@ -50,6 +54,10 @@ const TEXT_STREAM_THROTTLE_MS = 50;
 // Pending question resolver — used by AskUserQuestion hook
 let _questionResolve = null;
 
+// Queued clarification from the user (typed while AI is streaming)
+// Shape: { text: string, images: [{mediaType, base64Data}] } or null
+let _queuedClarification = null;
+
 const nodeConnector = global.createNodeConnector(CONNECTOR_ID, exports);
 
 /**
@@ -191,6 +199,7 @@ exports.cancelQuery = async function () {
         currentSessionId = null;
         // Clear any pending question
         _questionResolve = null;
+        _queuedClarification = null;
         return { success: true };
     }
     return { success: false };
@@ -214,6 +223,46 @@ exports.answerQuestion = async function (params) {
 exports.destroySession = async function () {
     currentSessionId = null;
     currentAbortController = null;
+    _queuedClarification = null;
+    return { success: true };
+};
+
+/**
+ * Queue a clarification message from the user (typed while AI is streaming).
+ * If text is already queued, appends with a newline.
+ */
+exports.queueClarification = async function (params) {
+    const newImages = params.images || [];
+    if (_queuedClarification) {
+        if (params.text) {
+            _queuedClarification.text += "\n" + params.text;
+        }
+        _queuedClarification.images = _queuedClarification.images.concat(newImages);
+    } else {
+        _queuedClarification = {
+            text: params.text || "",
+            images: newImages
+        };
+    }
+    return { success: true };
+};
+
+/**
+ * Get and clear the queued clarification (text + images).
+ * Called by the getUserClarification MCP tool.
+ */
+exports.getAndClearClarification = async function () {
+    const result = _queuedClarification;
+    _queuedClarification = null;
+    return result || { text: null, images: [] };
+};
+
+/**
+ * Clear any queued clarification without reading it.
+ * Used when the user clicks Edit on the queue bubble.
+ */
+exports.clearClarification = async function () {
+    _queuedClarification = null;
     return { success: true };
 };
 
@@ -228,7 +277,10 @@ async function _runQuery(requestId, prompt, projectPath, model, signal, locale,
     try {
         queryFn = await getQueryFn();
         if (!editorMcpServer) {
-            editorMcpServer = createEditorMcpServer(queryModule, nodeConnector);
+            editorMcpServer = createEditorMcpServer(queryModule, nodeConnector, {
+                hasClarification: function () { return !!_queuedClarification; },
+                getAndClearClarification: exports.getAndClearClarification
+            });
         }
     } catch (err) {
         nodeConnector.triggerPeer("aiError", {
@@ -258,7 +310,8 @@ async function _runQuery(requestId, prompt, projectPath, model, signal, locale,
             "mcp__phoenix-editor__execJsInLivePreview",
             "mcp__phoenix-editor__controlEditor",
             "mcp__phoenix-editor__resizeLivePreview",
-            "mcp__phoenix-editor__wait"
+            "mcp__phoenix-editor__wait",
+            "mcp__phoenix-editor__getUserClarification"
         ],
         agents: {
             "researcher": {
@@ -292,6 +345,8 @@ async function _runQuery(requestId, prompt, projectPath, model, signal, locale,
             "multiple Edit calls to make targeted changes rather than rewriting the entire " +
             "file with Write. This is critical because Write replaces the entire file content " +
             "which is slow and loses undo history." +
+            "\n\nWhen a tool response mentions the user has typed a clarification, immediately " +
+            "call getUserClarification to read it and incorporate the user's feedback into your current work." +
             (locale && !locale.startsWith("en")
                 ? "\n\nThe user's display language is " + locale + ". " +
                   "Respond in this language unless they write in a different language."
@@ -334,6 +389,9 @@ async function _runQuery(requestId, prompt, projectPath, model, signal, locale,
                                         " Reload when ready with execJsInLivePreview: `location.reload()`";
                                 }
                             }
+                            if (_queuedClarification) {
+                                reason += CLARIFICATION_HINT;
+                            }
                             return {
                                 hookSpecificOutput: {
                                     hookEventName: "PreToolUse",
@@ -370,6 +428,9 @@ async function _runQuery(requestId, prompt, projectPath, model, signal, locale,
                                     formatted = filePath + " (" +
                                         lines.length + " lines total)\n\n" + formatted;
                                     console.log("[Phoenix AI] Serving dirty file content for:", filePath);
+                                    if (_queuedClarification) {
+                                        formatted += CLARIFICATION_HINT;
+                                    }
                                     return {
                                         hookSpecificOutput: {
                                             hookEventName: "PreToolUse",
@@ -419,6 +480,9 @@ async function _runQuery(requestId, prompt, projectPath, model, signal, locale,
                                         " Reload when ready with execJsInLivePreview: `location.reload()`";
                                 }
                             }
+                            if (_queuedClarification) {
+                                reason += CLARIFICATION_HINT;
+                            }
                             return {
                                 hookSpecificOutput: {
                                     hookEventName: "PreToolUse",