@herbertgao/pi-extensions 2026.10.4 → 2026.10.6

package/node_modules/@herbertgao/pi-cc-extensions/extensions/renderer/tool/diff/diff-presentation.ts

@@ -1,5 +1,6 @@
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { pluralize } from "./diff-text.ts";
+import type { DiffTheme } from "./diff-palette.ts";
 import type { ToolDisplayConfig } from "../../../config/config.ts";
 
 export interface DiffSummaryStats {
@@ -68,3 +69,43 @@ export function buildDiffSummaryText(stats: DiffSummaryStats, width: number): st
 
 	return truncateToWidth(summaryCandidates[summaryCandidates.length - 1] ?? "", safeWidth, "");
 }
+
+/**
+ * 折叠摘要行样式：整行 muted，`+A -D` 用 diff 头行同一套绿/红，hover 只把动作词提到 text。
+ * 0 行预览与多行预览共用这一套颜色：改折叠行数时同一处信息不变色。
+ */
+export function styleDiffSummaryLine(
+	text: string,
+	stats: Pick<DiffSummaryStats, "added" | "removed"> | undefined,
+	hint: string,
+	theme: DiffTheme,
+	hovered: boolean,
+): string {
+	const counts = stats ? `+${stats.added} -${stats.removed}` : "";
+	const countsIndex = counts ? text.indexOf(counts) : -1;
+	const hintIndex = hint ? text.lastIndexOf(hint) : -1;
+	if (countsIndex < 0 && hintIndex < 0) {
+		return theme.fg("muted", text);
+	}
+
+	const pieces: string[] = [];
+	let cursor = 0;
+	const pushMuted = (end: number) => {
+		const gap = text.slice(cursor, end);
+		if (gap) pieces.push(theme.fg("muted", gap));
+	};
+	if (countsIndex >= 0 && stats) {
+		pushMuted(countsIndex);
+		pieces.push(theme.fg("toolDiffAdded", `+${stats.added}`));
+		pieces.push(theme.fg("muted", " "));
+		pieces.push(theme.fg("toolDiffRemoved", `-${stats.removed}`));
+		cursor = countsIndex + counts.length;
+	}
+	if (hintIndex >= cursor) {
+		pushMuted(hintIndex);
+		pieces.push(theme.fg(hovered ? "text" : "muted", hint));
+		cursor = hintIndex + hint.length;
+	}
+	pushMuted(text.length);
+	return pieces.join("");
+}

package/node_modules/@herbertgao/pi-cc-extensions/extensions/renderer/tool/diff/diff-renderer.ts

@@ -20,4 +20,8 @@ export { shouldHighlightCodeBlock } from "./diff-highlight.ts";
 export type { DisplayConfigInput } from "./diff-component.ts";
 export { isRichDiffComponent } from "./diff-component.ts";
 export { countEditDiffStats, renderEditDiffResult } from "./diff-edit-render.ts";
-export { countWriteDiffStats, renderWriteDiffResult } from "./diff-write-render.ts";
+export {
+	countWriteDiffStats,
+	renderWriteDiffResult,
+	writeStatsInCollapsedBody,
+} from "./diff-write-render.ts";

package/node_modules/@herbertgao/pi-cc-extensions/extensions/renderer/tool/diff/diff-text.ts

@@ -9,7 +9,8 @@ export function splitWriteContentLines(content: string): string[] {
 		return [];
 	}
 
-	const lines = content.split(/\r\n|\n|\r/);
+	const normalized = content.replace(/\r/g, "");
+	const lines = normalized.split("\n");
 	if (lines.length > 0 && lines[lines.length - 1] === "") {
 		lines.pop();
 	}

package/node_modules/@herbertgao/pi-cc-extensions/extensions/renderer/tool/diff/diff-write-render.ts

@@ -1,6 +1,7 @@
 import { Text, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import type { ToolDisplayConfig } from "../../../config/config.ts";
 import { sanitizeToolResultText } from "../../../utils/tool-result-sanitize.ts";
-import { showMoreHintText } from "../show-more-hint.ts";
+import { showMoreHintText } from "../names.ts";
 import { splitWriteContentLines } from "./diff-text.ts";
 import {
 	collectDiffStats,
@@ -54,6 +55,7 @@ import {
 	buildDiffSummaryText,
 	normalizeDiffRenderWidth,
 	resolveDiffPresentationMode,
+	styleDiffSummaryLine,
 	type DiffPresentationMode,
 } from "./diff-presentation.ts";
 
@@ -290,13 +292,14 @@ function renderWriteOverwriteGuardRows(
 	return renderSingleDiffRow(buildWriteOverwriteGuardText(guard, width), "warning", width, theme);
 }
 
-/** Folded write with `writeDiffCollapsedLines: 0`: `↳ created · click to show more`. */
+/** Folded write with `writeDiffCollapsedLines: 0`: `↳ diff +A -D · created · click to show more`. */
 function renderWriteCollapsedHintLine(
 	wasOverwrite: boolean,
 	width: number,
 	theme: DiffTheme,
 	hovered: boolean,
 	headerLabel?: string,
+	stats?: { added: number; removed: number },
 ): string[] {
 	const safeWidth = normalizeDiffRenderWidth(width);
 	if (safeWidth === 0) {
@@ -304,7 +307,20 @@ function renderWriteCollapsedHintLine(
 	}
 	const actionLabel = headerLabel?.trim() || (wasOverwrite ? "overwritten" : "created");
 	const clickLabel = showMoreHintText();
-	const candidates = [`↳ ${actionLabel} · ${clickLabel}`, `↳ ${actionLabel}`, actionLabel, "…"];
+	const counts = stats ? `+${stats.added} -${stats.removed}` : "";
+	const candidates = stats
+		? [
+				`↳ diff ${counts} · ${actionLabel} · ${clickLabel}`,
+				`↳ diff ${counts} · ${clickLabel}`,
+				`↳ diff ${counts} · ${actionLabel}`,
+				`↳ diff ${counts}`,
+				`↳ ${counts} · ${clickLabel}`,
+				`↳ ${actionLabel} · ${clickLabel}`,
+				`↳ ${actionLabel}`,
+				actionLabel,
+				"…",
+			]
+		: [`↳ ${actionLabel} · ${clickLabel}`, `↳ ${actionLabel}`, actionLabel, "…"];
 	let text = candidates[candidates.length - 1] ?? "…";
 	for (const candidate of candidates) {
 		if (visibleWidth(candidate) <= safeWidth) {
@@ -315,16 +331,21 @@ function renderWriteCollapsedHintLine(
 	if (visibleWidth(text) > safeWidth) {
 		text = truncateToWidth(text, safeWidth, "");
 	}
-	const clickIndex = text.lastIndexOf(clickLabel);
-	const styled =
-		hovered && clickIndex >= 0
-			? theme.fg("muted", text.slice(0, clickIndex)) +
-				theme.fg("text", clickLabel) +
-				theme.fg("muted", text.slice(clickIndex + clickLabel.length))
-			: theme.fg("muted", text);
+	const styled = styleDiffSummaryLine(text, stats, clickLabel, theme, hovered);
 	return [clampDiffLineToWidth(styled, safeWidth)];
 }
 
+/**
+ * 折叠 0 行预览时计数由正文那行显示（`↳ diff +A -D · created · click to show more`），
+ * 标题不再重复。compact 与 default 两个模式的写标题共用这条口径。
+ */
+export function writeStatsInCollapsedBody(
+	expanded: boolean,
+	display: Pick<ToolDisplayConfig, "writeDiffCollapsedLines">,
+): boolean {
+	return !expanded && resolveWriteCollapsedLimit(display) === 0;
+}
+
 /**
  * write 变更行统计（compact 单行用）：复用当前 write diff 算法。
  * 新文件 = 全部新内容为 added；覆盖已有文件用 LCS 精确统计。
@@ -413,6 +434,10 @@ export function renderWriteDiffResult(
 			const hint = cache.getHintLine();
 			return hint !== undefined && normalizeCollapsedHintLine(plainLine) === hint;
 		},
+		/** 折叠 0 行预览时正文那行自带 +A -D：标题不再重复计数。 */
+		bodyShowsStats(): boolean {
+			return writeStatsInCollapsedBody(options.expanded, resolveLiveDisplayConfig(config));
+		},
 		render(width: number): string[] {
 			// Live config: panel can change indicator/wrap/limits after this component is created.
 			const live = resolveLiveDisplayConfig(config);
@@ -445,6 +470,7 @@ export function renderWriteDiffResult(
 					theme,
 					hovered,
 					options.headerLabel,
+					countWriteDiffStats(content, options.previousContent, options.fileExistedBeforeWrite),
 				);
 				return cache.set(
 					safeWidth,

package/node_modules/@herbertgao/pi-cc-extensions/extensions/renderer/tool/diff/line-width-safety.ts

@@ -1,6 +1,6 @@
 import { normalizeDiffRenderWidth } from "./diff-presentation.ts";
 import { pluralize } from "./diff-text.ts";
-import { showMoreHintText } from "../show-more-hint.ts";
+import { showMoreHintText } from "../names.ts";
 
 export interface WidthMeasurementOps {
 	measure(text: string): number;

package/node_modules/@herbertgao/pi-cc-extensions/extensions/renderer/tool/grouping.ts

@@ -8,6 +8,12 @@ import {
 } from "@earendil-works/pi-tui";
 import { config } from "../../config/config.ts";
 import { TOOL_LOADING_INTERVAL_MS, toolLoadingIcon } from "../../utils/tool-loading-icon.ts";
+import {
+	ASK_USER_QUESTION_TOOL_NAME,
+	askUserAnswerText,
+	askUserAnswers,
+	type AskUserAnswer,
+} from "./ask-user-question.ts";
 import {
 	CODEMODE_TOOL_NAME,
 	codemodeCalls,
@@ -16,17 +22,19 @@ import {
 } from "./codemode.ts";
 import { getToolMouseTui } from "../mouse/scroll.ts";
 import { mcpToolTitle } from "./mcp-title.ts";
-import { collapseHintText, isToolTuiFullscreen, showMoreHintText } from "./show-more-hint.ts";
+import { collapseHintText, isToolTuiFullscreen, showMoreHintText } from "./names.ts";
 import { stripAnsi, stripBackgroundAnsi, stripLeadingStatusIcon } from "../../utils/ansi-text.ts";
 import { walkComponentTree } from "../../utils/component-tree.ts";
 import {
 	fitToolCallSummary,
 	humanizeToolLabel,
 	renderToolSummary,
+	SHELL_TOOL_NAMES,
 	toolCallSummary,
 	type ToolCallSummary,
 } from "./names.ts";
-import { toolViewportWidth } from "./result.ts";
+import { formatToolDuration, headTruncateToWidth, toolViewportWidth } from "./result.ts";
+import { isLiveToolCall } from "./tool-state.ts";
 import {
 	patchRegistry,
 	TOOL_GROUPING_GENERATION_KEY as GENERATION_KEY,
@@ -108,6 +116,12 @@ function statusIcon(value: ToolStatus): string {
 	return toolLoadingIcon();
 }
 
+/** 等待窗口或运行中的行：spinner 逐帧变化，分组卡要跟着跳帧。 */
+function isAnimatingTool(tool: any): boolean {
+	if (status(tool) !== "pending") return false;
+	return Boolean(tool?.executionStarted) || isLiveToolCall(tool?.toolCallId);
+}
+
 function scheduleGroupAnimation(patch: Patch): void {
 	if (patch.animationTimer || !patch.active) return;
 	patch.animationTimer = setTimeout(() => {
@@ -115,11 +129,7 @@ function scheduleGroupAnimation(patch: Patch): void {
 		if (!patch.active) return;
 		let needsRender = false;
 		for (const group of patch.groups) {
-			if (
-				(group.children as any[]).some(
-					(tool) => tool?.executionStarted && status(tool) === "pending",
-				)
-			) {
+			if ((group.children as any[]).some(isAnimatingTool)) {
 				group.invalidate();
 				// 分组卡不是 ToolExecutionComponent：它的 invalidate() 不会请求渲染，
 				// 不补这一步 spinner 只在别人渲染时才跳帧（并行工具下表现为卡顿/冻结）。
@@ -203,6 +213,39 @@ function toolSummary(tool: any): ToolCallSummary {
  * codemode 的折叠行：有结果就报该次调用的统计（与单卡汇总行同一套口径），
  * 免得一张卡里几行长代码预览互相看不出区别。还没结果时退回代码预览。
  */
+/**
+ * ask_user_question 的折叠行：有结果就报「问题 -> 回答」，
+ * 多题压成一行并标注剩余条数。还没结果时退回问题预览。
+ */
+function askUserResultSummary(tool: any): ToolCallSummary | undefined {
+	if (toolName(tool) !== ASK_USER_QUESTION_TOOL_NAME || !tool?.result) return undefined;
+	const answers = askUserAnswers(tool.result)
+		.map((answer: AskUserAnswer, index: number) => ({ answer, index }))
+		.sort((left, right) => {
+			const leftIndex = Number(left.answer.questionIndex);
+			const rightIndex = Number(right.answer.questionIndex);
+			const leftMissing = !Number.isFinite(leftIndex);
+			const rightMissing = !Number.isFinite(rightIndex);
+			if (leftMissing || rightMissing) {
+				if (leftMissing !== rightMissing) return leftMissing ? 1 : -1;
+				return left.index - right.index;
+			}
+			return leftIndex - rightIndex;
+		})
+		.map((entry) => entry.answer);
+	if (answers.length === 0) {
+		const label = tool.result?.details?.cancelled === true ? "Declined" : "Done";
+		return { main: `${toolTitle(tool)} ${label}`, detail: "" };
+	}
+	const first = answers[0]!;
+	const question = String(first.question ?? "").trim() || "Question";
+	const more = answers.length > 1 ? ` (+${answers.length - 1})` : "";
+	return {
+		main: `${toolTitle(tool)} ${question} -> ${askUserAnswerText(first)}${more}`,
+		detail: "",
+	};
+}
+
 function codemodeResultSummary(tool: any): ToolCallSummary | undefined {
 	if (toolName(tool) !== CODEMODE_TOOL_NAME || !tool?.result) return undefined;
 	const parts = codemodeSummaryParts(
@@ -213,10 +256,83 @@ function codemodeResultSummary(tool: any): ToolCallSummary | undefined {
 	return { main: `${toolTitle(tool)} ${parts.join(" · ")}`, detail: "" };
 }
 
+/**
+ * 组内 shell 行的尾巴：只报耗时（`· 12.4s`）。输出和错误正文都在展开后看；
+ * 失败靠行首的 ✗，组头另有 failed 计数。
+ * 耗时取 pi 记在结果上的 durationMs（单卡渲染上下文里的同一个值），运行中还拿不到就不报。
+ */
+function shellResultTail(
+	tool: any,
+	fg: (color: string, text: string) => string,
+	toolStatus: ToolStatus,
+): string {
+	if (!SHELL_TOOL_NAMES.has(toolName(tool)) || toolStatus === "pending" || !tool?.result) return "";
+	const durationMs = tool.result?.durationMs;
+	const duration =
+		typeof durationMs === "number" && Number.isFinite(durationMs) && durationMs >= 0
+			? formatToolDuration(durationMs)
+			: "";
+	return duration ? ` ${fg("dim", `· ${duration}`)}` : "";
+}
+
+/** 分组折叠态的一行子工具：`├/└` + 状态图标 + 与组内同一套摘要。 */
+function collapsedGroupToolLine(
+	tool: any,
+	last: boolean,
+	fg: (color: string, text: string) => string,
+	width: number,
+): string {
+	const toolStatus = status(tool);
+	const color = toolStatus === "pending" ? "accent" : toolStatus;
+	const summary = askUserResultSummary(tool) ?? codemodeResultSummary(tool) ?? toolSummary(tool);
+	const prefix = ` ${fg("dim", last ? "└" : "├")} ${fg(color, statusIcon(toolStatus))} `;
+	const detail = fg("dim", summary.detail);
+	const result = shellResultTail(tool, fg, toolStatus);
+	const rowWidth = toolViewportWidth(width);
+	const mainWidth = Math.max(
+		0,
+		rowWidth - visibleWidth(prefix) - visibleWidth(detail) - visibleWidth(result),
+	);
+	return truncateToWidth(
+		`${prefix}${renderToolSummary(summary, mainWidth, fg)}${detail}${result}`,
+		rowWidth,
+		"",
+	);
+}
+
+type GroupHeaderCounts = { pending: number; success: number; error: number };
+
+/** 组头计数：`2 done · 1 failed`。没有计数时返回空串。 */
+function groupCountText(
+	counts: GroupHeaderCounts,
+	fg: (color: string, text: string) => string,
+): string {
+	return (["pending", "success", "error"] as const)
+		.filter((key) => counts[key])
+		.map((key) => {
+			const label = key === "pending" ? "running" : key === "success" ? "done" : "failed";
+			const color = key === "pending" ? "accent" : key;
+			return `${fg(color, String(counts[key]))} ${label}`;
+		})
+		.join(` ${fg("dim", "·")} `);
+}
+
+/** 组头圆点色：有失败取 error，否则有运行中取 accent，否则 success。 */
+function groupOverallStatus(counts: GroupHeaderCounts): ToolStatus {
+	return counts.error ? "error" : counts.pending ? "pending" : "success";
+}
+
+/**
+ * 组头的工具列表：名称用与单组标题、子行同一套人性化写法，次数一律带上（各跑一次也报 ×1）。
+ * 同名（同显示标题）的合并成一项，避免 `MCP call×1, MCP call×1` 这种重复。
+ */
 function toolNameList(tools: any[]): string {
 	const counts = new Map<string, number>();
-	for (const tool of tools) counts.set(toolName(tool), (counts.get(toolName(tool)) ?? 0) + 1);
-	return [...counts].map(([name, count]) => `${name}${count > 1 ? `×${count}` : ""}`).join(", ");
+	for (const tool of tools) {
+		const label = toolTitle(tool);
+		counts.set(label, (counts.get(label) ?? 0) + 1);
+	}
+	return [...counts].map(([label, count]) => `${label}×${count}`).join(", ");
 }
 
 let nextGroupId = 1;
@@ -378,42 +494,27 @@ export class ToolGroupComponent extends Container {
 		const fg = (color: string, text: string) => theme?.fg?.(color, text) ?? text;
 		const counts = { pending: 0, success: 0, error: 0 };
 		for (const tool of this.children) counts[status(tool)]++;
-		const countText = (["pending", "success", "error"] as const)
-			.filter((key) => counts[key])
-			.map((key) => {
-				const label = key === "pending" ? "running" : key === "success" ? "done" : "failed";
-				const color = key === "pending" ? "accent" : key;
-				return `${fg(color, String(counts[key]))} ${label}`;
-			})
-			.join(` ${fg("dim", "·")} `);
+		const countText = groupCountText(counts, fg);
 		const names = new Set(this.children.map(toolName));
 		const label = names.size === 1 ? toolTitle(this.children[0]) : "Multiple Tools";
-		const overall: ToolStatus = counts.error ? "error" : counts.pending ? "pending" : "success";
-		if (
-			(this.children as any[]).some((tool) => tool?.executionStarted && status(tool) === "pending")
-		)
-			scheduleGroupAnimation(this.patch);
+		const overall = groupOverallStatus(counts);
+		if ((this.children as any[]).some(isAnimatingTool)) scheduleGroupAnimation(this.patch);
 		const overallColor = overall === "pending" ? "accent" : overall;
-		const nameList = names.size > 1 ? ` ${fg("dim", `· ${toolNameList(this.children)}`)}` : "";
 		// 圆点保持 dim；hover 只高亮可点击文字。
 		const hintText = this._expanded ? collapseHintText() : showMoreHintText();
 		const hint = `${fg("dim", "·")} ${fg(this.hintHovered ? "text" : "dim", hintText)}`;
-		// 行尾提示承载折叠分组的可点击区（collapsedHintHitbox 依赖行尾短语）。
-		// 空间不足时先省略工具名列表，再截断计数尾部，提示最后让位；
-		// 极窄视口连“圆点+标题+计数”都放不下时才回退整行截断。
-		const viewport = toolViewportWidth(width);
+		const rowWidth = toolViewportWidth(width);
+		// 工具列表让位给展开提示：提示被截断的话，鼠标层要在行尾找 `click to show more`
+		// 就找不到，整张卡在窄宽度下点不开。名字截断后子行里仍能看全。
 		const head = ` ${fg(overallColor, "●")} ${label}: ${countText}`;
-		const hintWidth = visibleWidth(` ${hint}`);
-		const nameBudget = viewport - visibleWidth(head) - hintWidth;
-		const elidedName =
-			nameList && nameBudget < visibleWidth(nameList)
-				? nameBudget >= 4
-					? ` ${fg("dim", "…")}`
-					: ""
-				: nameList;
-		const headBudget = viewport - hintWidth - visibleWidth(elidedName);
-		const titleLine = `${visibleWidth(head) <= headBudget ? head : truncateToWidth(head, headBudget, "…")}${elidedName} ${hint}`;
-		const lines = ["", truncateToWidth(titleLine, viewport, "…")];
+		const tail = ` ${hint}`;
+		const listRoom = rowWidth - visibleWidth(head) - visibleWidth(tail) - 3;
+		// 连一个工具名都放不下就不放列表：退化成 `· …` 只会把行撑爆。
+		const nameList =
+			names.size > 1 && listRoom >= 4
+				? ` ${fg("dim", `· ${headTruncateToWidth(toolNameList(this.children), listRoom)}`)}`
+				: "";
+		const lines = ["", truncateToWidth(`${head}${nameList}${tail}`, rowWidth, "")];
 		const total = this.children.length;
 		const childPaints = this._expanded
 			? (this.children as any[]).map((tool) => tool.render?.(Math.max(1, width - 2)))
@@ -441,19 +542,7 @@ export class ToolGroupComponent extends Container {
 			const branch = index === total - 1 ? "└" : "├";
 			const continuation = index === total - 1 ? "  " : "│ ";
 			if (!this._expanded) {
-				const summary = codemodeResultSummary(tool) ?? toolSummary(tool);
-				const prefix = ` ${fg("dim", branch)} ${fg(color, statusIcon(toolStatus))} `;
-				const detail = fg("dim", summary.detail);
-				// 与单工具卡标题同宽，宽屏右侧留白一致
-				const rowWidth = toolViewportWidth(width);
-				const mainWidth = Math.max(0, rowWidth - visibleWidth(prefix) - visibleWidth(detail));
-				lines.push(
-					truncateToWidth(
-						`${prefix}${renderToolSummary(summary, mainWidth, fg)}${detail}`,
-						rowWidth,
-						"",
-					),
-				);
+				lines.push(collapsedGroupToolLine(tool, index === total - 1, fg, width));
 				continue;
 			}
 			const rendered = visibleLines(Array.isArray(childPaints?.[index]) ? childPaints[index] : []);

package/node_modules/@herbertgao/pi-cc-extensions/extensions/renderer/tool/message-display.ts

@@ -6,7 +6,7 @@ import {
 import { Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import { MESSAGE_DISPLAY_PATCH, patchRegistry } from "../../utils/patch-keys.ts";
 import { config } from "../../config/config.ts";
-import { showMoreHintText } from "./show-more-hint.ts";
+import { showMoreHintText } from "./names.ts";
 import { walkComponentTree } from "../../utils/component-tree.ts";
 
 /**

package/node_modules/@herbertgao/pi-cc-extensions/extensions/renderer/tool/names.ts

@@ -1,13 +1,13 @@
 import { posix, win32 } from "node:path";
 import type { ThemeColor } from "@earendil-works/pi-coding-agent";
-import { visibleWidth } from "@earendil-works/pi-tui";
+import { getKeybindings, visibleWidth } from "@earendil-works/pi-tui";
 import { config } from "../../config/config.ts";
 import { oneLine } from "../../utils/format.ts";
 import { headTruncateToWidth } from "./result.ts";
 
-/** inputClip=0 时不设字符上限，交给渲染时的实际宽度截断。 */
+/** toolLabelClip=0 时不设字符上限，交给渲染时的实际宽度截断。 */
 function clipLimit(): number {
-	return config.inputClip > 0 ? config.inputClip : Number.POSITIVE_INFINITY;
+	return config.toolLabelClip > 0 ? config.toolLabelClip : Number.POSITIVE_INFINITY;
 }
 
 function clip(value: unknown): string {
@@ -157,7 +157,7 @@ function pathSummary(
 }
 
 /** 入参是 shell 命令的工具。 */
-const SHELL_TOOL_NAMES = new Set(["bash", "powershell", "pwsh", "sh", "zsh", "cmd"]);
+export const SHELL_TOOL_NAMES = new Set(["bash", "powershell", "pwsh", "sh", "zsh", "cmd"]);
 
 /** 内置检索工具：pattern 缺失（无效调用）时保留 "…" 占位。 */
 const SEARCH_TOOL_NAMES = new Set(["grep", "find"]);
@@ -427,3 +427,43 @@ export function renderToolSummary(
 		? `${fg("toolTitle", title)}${fg("dim", headTruncateToWidth(` ${summary.payload}`, room))}`
 		: fg("toolTitle", title);
 }
+
+let toolTuiFullscreen: boolean | undefined;
+
+export function setToolTuiFullscreen(value: boolean): void {
+	toolTuiFullscreen = value;
+}
+
+export function isToolTuiFullscreen(): boolean {
+	return toolTuiFullscreen !== false;
+}
+
+function formatKeyPart(part: string): string {
+	// 与 pi 内置 keybinding-hints 一致：macOS 上 alt 显示为 option
+	return process.platform === "darwin" && part.toLowerCase() === "alt" ? "option" : part;
+}
+
+/** 默认展开快捷键（app.tools.expand）显示文本；未配置时回退 ctrl+o。 */
+export function expandShortcutText(): string {
+	const keys = getKeybindings().getKeys("app.tools.expand");
+	if (keys.length === 0) return "ctrl+o";
+	return keys
+		.join("/")
+		.split("/")
+		.map((part) => part.split("+").map(formatKeyPart).join("+"))
+		.join("/");
+}
+
+export function showMoreHintText(): string {
+	return isToolTuiFullscreen() ? "click to show more" : `${expandShortcutText()} to show more`;
+}
+
+/** 展开卡的收起提示，与折叠态 showMoreHintText 同一位置对称。 */
+export function collapseHintText(): string {
+	return isToolTuiFullscreen() ? "↑ Collapse" : `${expandShortcutText()} to collapse`;
+}
+
+/** 该行是否带展开态收起提示（用于展开卡的 hint hover 命中）。 */
+export function isCollapseHintLine(plainLine: string): boolean {
+	return plainLine.includes(collapseHintText());
+}