fix(widgets): add max line limit and document multi-hook behavior

- Limit total widget lines to 10 to prevent viewport overflow/flicker
- Show '... (widget truncated)' when limit exceeded
- Document that multiple hooks stack widgets vertically
- Add caution about keeping widgets small

packages/coding-agent/docs/hooks.md

@@ -445,9 +445,10 @@ const currentText = ctx.ui.getEditorText();
 
 **Widget notes:**
 - Widgets are multi-line displays shown above the editor (below "Working..." indicator)
-- Multiple hooks can set widgets using unique keys
+- Multiple hooks can set widgets using unique keys (all widgets are displayed, stacked vertically)
 - Use for progress lists, todo tracking, or any multi-line status
 - Supports ANSI styling via `ctx.ui.theme` (including `strikethrough`)
+- **Caution:** Keep widgets small (a few lines). Large widgets from multiple hooks can cause viewport overflow and TUI flicker.
 
 **Styling with theme colors:**
 

packages/coding-agent/src/modes/interactive/interactive-mode.ts

@@ -637,6 +637,9 @@ export class InteractiveMode {
 		this.renderWidgets();
 	}
 
+	// Maximum total widget lines to prevent viewport overflow
+	private static readonly MAX_WIDGET_LINES = 10;
+
 	/**
 	 * Render all hook widgets to the widget container.
 	 */
@@ -649,10 +652,18 @@ export class InteractiveMode {
 			return;
 		}
 
-		// Render each widget
+		// Render each widget, respecting max lines to prevent viewport overflow
+		let totalLines = 0;
 		for (const [_key, lines] of this.hookWidgets) {
 			for (const line of lines) {
+				if (totalLines >= InteractiveMode.MAX_WIDGET_LINES) {
+					// Add truncation indicator and stop
+					this.widgetContainer.addChild(new Text(theme.fg("muted", "... (widget truncated)"), 1, 0));
+					this.ui.requestRender();
+					return;
+				}
 				this.widgetContainer.addChild(new Text(line, 1, 0));
+				totalLines++;
 			}
 		}