Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

Short display names for the built-in tools (#688)

Yaowei Zheng7c2bfd5270c0
diff --git a/changelog/unreleased/2026-09-11-tool-name-aliases.md b/changelog/unreleased/2026-09-11-tool-name-aliases.md
new file mode 100644
index 00000000..45a8a972
--- /dev/null
+++ b/changelog/unreleased/2026-09-11-tool-name-aliases.md
@@ -0,0 +1,29 @@
+# Tool cards name the built-in tools by a short alias
+
+- **Date:** 2026-09-11
+- **Type:** feature
+- **Scope:** `web`
+- **PR:** [#688](https://github.com/Prism-Shadow/penguin-harness/pull/688)
+
+[中文版](2026-09-11-tool-name-aliases.zh.md)
+
+A tool-call card in a conversation now names each of the seven built-in tools by a short alias
+instead of the name the model calls it by: `read_file` reads as "read", `write_file` as "write",
+`edit_file` as "edit", `exec_command` as "exec", `input_command` as "follow", `run_subagent` as
+"subagent" and `input_subagent` as "communicate", with the Chinese dictionary carrying its own
+wording. Appearance settings gained a "Tool short names" switch, on by default, that turns the
+aliases off.
+
+## Details
+
+- The alias appears in the two places the card spells a tool name: the collapsed row's header and
+ the pending-approval block's name pill. Both keep the tool's own name in their tooltip whenever
+ an alias is shown.
+- Only the built-in tools are aliased. MCP tools and the names older Traces still carry
+ (`kill_command`, `read_image`, `describe_image`, `kill_subagent`) render unchanged in either
+ switch position.
+- The Trace viewer, the Agent settings tools table and the Cost Center's error codes keep the
+ tool's own name, as do every approval rule and every comparison the app makes on a tool name —
+ the alias is resolved at the render expression and nowhere else.
+- The preference is stored per browser under `penguin.toolAliases`, alongside the other Appearance
+ choices.
diff --git a/changelog/unreleased/2026-09-11-tool-name-aliases.zh.md b/changelog/unreleased/2026-09-11-tool-name-aliases.zh.md
new file mode 100644
index 00000000..5de10299
--- /dev/null
+++ b/changelog/unreleased/2026-09-11-tool-name-aliases.zh.md
@@ -0,0 +1,23 @@
+# 工具卡片用短名称呼内置工具
+
+- **Date:** 2026-09-11
+- **Type:** feature
+- **Scope:** `web`
+- **PR:** [#688](https://github.com/Prism-Shadow/penguin-harness/pull/688)
+
+[English](2026-09-11-tool-name-aliases.md)
+
+对话里的工具卡片不再显示模型调用工具时用的名字,而是用短名称呼七个内置工具:`read_file` 显示为
+「读取」、`write_file` 为「写入」、`edit_file` 为「编辑」、`exec_command` 为「执行命令」、
+`input_command` 为「跟进命令」、`run_subagent` 为「子智能体」、`input_subagent` 为「交流」,英文界面
+另有一套自己的措辞。外观设置新增「工具短名」开关,默认开启,关掉即恢复原名。
+
+## 细节
+
+- 短名出现在卡片写出工具名的两处:折叠行的标题,以及待审批区块的名称标签。只要显示的是短名,两处的
+ tooltip 都给出工具本来的名字。
+- 只有内置工具有短名。MCP 工具与旧 Trace 里才有的名字(`kill_command`、`read_image`、
+ `describe_image`、`kill_subagent`)在开关的两个位置都照原样显示。
+- 轨迹观测、智能体设置的工具表、成本中心的错误码仍是工具原本的名字,审批规则与应用内一切按工具名做的
+ 判断也是——短名只在渲染那一处解析,不流向别处。
+- 该偏好按浏览器记忆,键为 `penguin.toolAliases`,与其余外观选项同处。
diff --git a/packages/docs/content/web-app.en.md b/packages/docs/content/web-app.en.md
index acf5b6fe..4ecfa5c4 100644
--- a/packages/docs/content/web-app.en.md
+++ b/packages/docs/content/web-app.en.md
@@ -55,7 +55,7 @@ Pinning is offered only in the active list — the archived, subagent and schedu
### Streaming Rendering
- Model text renders token by token; thinking blocks are collapsible;
-- Tool cards expand to show arguments and output, with a live timer while running; a call made with `run_in_background` carries the same activity trace as the conversation list, right of its duration ("Runs in the background") — the call returns at once, and the mark says its work did not;
+- Tool cards expand to show arguments and output, with a live timer while running; a call made with `run_in_background` carries the same activity trace as the conversation list, right of its duration ("Runs in the background") — the call returns at once, and the mark says its work did not; a card heads itself with a short name for the built-in tools (`read_file` reads as "read"), keeping the tool's own name in the tooltip, and the **Tool short names** switch on the Appearance settings page turns that off — every other tool, MCP tools included, always reads as itself;
- A context compaction leaves a row whose title doubles as its status, the work-group header's Running/Done idiom: Compacting while it runs and Compacted once it settles (Clearing/Cleared for a discard), with its wall time; while a summarize runs the row is open: its thinking section appears once the request's thinking arrives, and its result section only after that thinking finishes, when the first summary text lands — each closed by default, each with its own wall time — and the row closes itself again once the compaction settles, leaving the one line; a failed compaction keeps the bare mode word (Compaction, or Clear) over a one-line reason instead;
- Subagents leave a full-width row in the stream, styled like the other collapsed step rows (agent avatar, name, short session id, running spinner, and an amber dot while one of their tool calls awaits approval); clicking it opens the agents side panel — a call graph of that row's Task on top (each node shows its elapsed time; click a node to switch) and the selected child's live conversation below — the child's own user prompts included — where nested tool cards and approvals work exactly as in the main chat. Panel visibility is task-scoped: sending a message that starts a new task closes it by default (entering a session starts closed too), and it comes back when you open it yourself or — on desktop — when the current task spawns a subagent (one auto-open per task; a manual close holds until the next task; never over an open files panel). Opening the panel from the toolbar, or switching sessions, shows the latest Task's graph; a row on an older turn brings back that turn's graph. The agents panel and the Workspace files panel never show together — opening one closes the other. Context compaction and the first-run MCP connect show a unified step row (the work-group header shell, sticky title bar included — running/success/failure only swap the icon and the one-line detail, with the wall time on the result; the MCP row leads with the discovered-tool count and names unavailable servers, and expands into one group per server — status, tool count and that server's connect time — each opening into its tool list or the failure detail);
- After each Task, a stats line shows tokens, TPS, elapsed time, cost, copy, and a **Fork** action to the right of copy. Fork asks for confirmation first — it duplicates the conversation into a new chat — and only then opens a new Session at that completed assistant reply with the same Agent, model, Workspace, approval mode, and retained transcript. Forks from different replies in one source chat share an increasing, language-neutral title sequence (`Source title (1)`, `Source title (2)`). Its Trace and scratchpad are independent snapshots: local images/files keep rendering even after the source chat is deleted;
diff --git a/packages/docs/content/web-app.zh.md b/packages/docs/content/web-app.zh.md
index feada6c8..65e78f65 100644
--- a/packages/docs/content/web-app.zh.md
+++ b/packages/docs/content/web-app.zh.md
@@ -55,7 +55,7 @@ penguin web
### 流式渲染
- 模型文本逐 Token 渲染,思考块可折叠;
-- 工具卡片可展开查看参数与输出,执行中显示实时计时;以 `run_in_background` 发起的调用在用时右侧带与会话列表同一枚活动波形标记(「在后台运行」)——调用本身立刻返回,标记说明它的工作没有;
+- 工具卡片可展开查看参数与输出,执行中显示实时计时;以 `run_in_background` 发起的调用在用时右侧带与会话列表同一枚活动波形标记(「在后台运行」)——调用本身立刻返回,标记说明它的工作没有;卡片以短名称呼内置工具(`read_file` 显示为「读取」),工具本来的名字留在 tooltip 里,设置页「外观」的**工具短名**开关可关掉它——其余工具(含 MCP 工具)始终显示原名;
- 上下文压缩在消息流中留下一行,标题兼作状态、与工作分组组头的「运行中」/「运行完毕」同一写法:按实际动作写作「压缩中」/「压缩完毕」,discard 则为「清空中」/「清空完毕」,并带用时;summarize 运行期间该行展开:压缩请求的思考一到就出现「思考」一节,「压缩结果」一节要等思考结束、第一段摘要文本抵达后才出现——两节默认折叠、各带自己的用时——压缩结束后该行自行收起,只留下这一行;失败的压缩保留裸的「压缩」或「清空」标题与一行原因;
- 子 Agent 在消息流中只留下一条通栏行,样式与其他折叠步骤行一致(头像、名称、短会话号、运行中转圈,子会话内有待审批时带琥珀色圆点);点击打开右侧智能体面板——上方是该行所属 Task 派生关系的调用图(节点上显示运行时长,点节点切换),下方是所选子会话的实时对话(含子会话自己的用户消息),嵌套工具卡片与审批与主对话完全一致;面板的显示以任务为界:发送消息开启新任务时默认关闭(进入会话时同样默认关闭),仅在手动打开、或(桌面端)当前任务派生子智能体时重新显示(每个任务自动打开一次,任务内手动关闭后保持关闭到下个任务,且不抢占已打开的工作区面板);从工具条打开面板或切换 Session 时默认展示最新 Task 的调用图,点旧轮次的行则回看那一轮的调用图;智能体面板与工作区面板不会同时显示,打开一个即关闭另一个;上下文压缩与首次 MCP 连接以统一样式的步骤行提示(与运行分组头同款外壳,含吸顶标题栏,连接中/成功/失败仅切换图标与单行详情,结果行含耗时;MCP 行主显发现的工具数并点名不可用的 Server,展开后按 Server 分组——每组一行状态、工具数与该 Server 的连接耗时,点开组内是工具列表或失败原因);
- 每个 Task 结束后显示统计行:Token 用量、TPS、耗时、费用、复制以及位于复制按钮右侧的**分叉**操作。分叉会先弹出确认框(该操作会把对话复制为一个新对话),确认后才在该条已完成的模型回复处新建 Session,沿用 Agent、模型、Workspace、审批模式和保留范围内的历史;同一源对话从不同回复分叉时,标题使用不依赖界面语言的编号后缀,按 `原标题 (1)`、`原标题 (2)` 递增。新旧会话的 Trace 与 scratchpad 是独立快照,即使删除源对话,本地图片和附件仍可显示;
diff --git a/packages/web/e2e/chat.spec.mjs b/packages/web/e2e/chat.spec.mjs
index e3b6b4de..03cabdf6 100644
--- a/packages/web/e2e/chat.spec.mjs
+++ b/packages/web/e2e/chat.spec.mjs
@@ -55,8 +55,10 @@ test("chat + tool approval + stats/cost/copy + traces + files", async ({ page })
await ta.fill("Help me set up @theme");
await page.getByRole("button", { name: "发送" }).click();
- // Tool name is shown on the collapsed tool row + in the pending-approval block.
- await expect(page.getByText("exec_command").first()).toBeVisible();
+ // The tool name is shown on the collapsed tool row + in the pending-approval block, as the
+ // short display name the Appearance switch turns on by default (`exec_command` itself stays
+ // in the tooltip of both, which is not text).
+ await expect(page.getByText("执行命令").first()).toBeVisible();
// Thinking + tool calls are wrapped in a work group; header shows running/done status.
await expect(page.getByText("运行中").first()).toBeVisible();
@@ -104,10 +106,7 @@ test("chat + tool approval + stats/cost/copy + traces + files", async ({ page })
await runningGroup.click(); // toggle → marks the group user-toggled (open := false)
await runningGroup.click(); // toggle back → the user is deliberately keeping it open
- const toolCard = page
- .locator("button[aria-expanded]")
- .filter({ hasText: "exec_command" })
- .first();
+ const toolCard = page.locator("button[aria-expanded]").filter({ hasText: "执行命令" }).first();
await toolCard.click();
await expect(toolCard).toHaveAttribute("aria-expanded", "true");
@@ -161,7 +160,7 @@ test("chat + tool approval + stats/cost/copy + traces + files", async ({ page })
// Turn is over and the stats line has landed. The card is still open — which also proves the
// group did not collapse (a collapsed group unmounts its body, so the card would be gone).
await expect(
- page.locator("button[aria-expanded]").filter({ hasText: "exec_command" }).first(),
+ page.locator("button[aria-expanded]").filter({ hasText: "执行命令" }).first(),
).toHaveAttribute("aria-expanded", "true");
// The stats line IS the AI reply's footer (bottom-left, mirroring the user footer's bottom-right):
diff --git a/packages/web/e2e/outline.spec.mjs b/packages/web/e2e/outline.spec.mjs
index 6508fdf9..1eb131f0 100644
--- a/packages/web/e2e/outline.spec.mjs
+++ b/packages/web/e2e/outline.spec.mjs
@@ -211,7 +211,7 @@ test("minimap ticks + hover preview + jump, five-turn gate, sticky group header,
const header = page.locator("[data-group-header]");
await expect(header).toHaveCount(1);
await header.click();
- await page.locator("button[aria-expanded]").filter({ hasText: "exec_command" }).first().click();
+ await page.locator("button[aria-expanded]").filter({ hasText: "执行命令" }).first().click();
await expect(page.getByText("line 40")).toBeVisible();
// Scrolled into the middle of the tool output, the two sticky levels stack: the group
diff --git a/packages/web/e2e/reload-midstream.spec.mjs b/packages/web/e2e/reload-midstream.spec.mjs
index a633cc94..c5c701f5 100644
--- a/packages/web/e2e/reload-midstream.spec.mjs
+++ b/packages/web/e2e/reload-midstream.spec.mjs
@@ -64,10 +64,7 @@ async function openToolOutput(page) {
} else if ((await group.getAttribute("aria-expanded")) !== "true") {
await group.click(); // finished and collapsed: open it to reach the card
}
- const toolCard = page
- .locator("button[aria-expanded]")
- .filter({ hasText: "exec_command" })
- .first();
+ const toolCard = page.locator("button[aria-expanded]").filter({ hasText: "执行命令" }).first();
await expect(toolCard).toBeVisible();
if ((await toolCard.getAttribute("aria-expanded")) !== "true") await toolCard.click();
await expect(toolCard).toHaveAttribute("aria-expanded", "true");
@@ -83,7 +80,7 @@ async function startSlowToolRun(page, sessionId) {
await ta.waitFor();
await ta.fill("slow stream test");
await page.getByRole("button", { name: "发送" }).click();
- await expect(page.getByText("exec_command").first()).toBeVisible();
+ await expect(page.getByText("执行命令").first()).toBeVisible();
await page.getByRole("button", { name: "允许" }).click();
const outputPre = await openToolOutput(page);
await expect(outputPre).toContainText("line 3");
diff --git a/packages/web/e2e/steer-abort.spec.mjs b/packages/web/e2e/steer-abort.spec.mjs
index d165d836..6a09d3b0 100644
--- a/packages/web/e2e/steer-abort.spec.mjs
+++ b/packages/web/e2e/steer-abort.spec.mjs
@@ -55,7 +55,7 @@ test("interrupting mid-tool-call returns the queued steering message to the comp
await ta.waitFor();
await ta.fill("slow stream test");
await page.getByRole("button", { name: "发送" }).click();
- await expect(page.getByText("exec_command").first()).toBeVisible();
+ await expect(page.getByText("执行命令").first()).toBeVisible();
await page.getByRole("button", { name: "允许" }).click();
// Steer while the ~8s tool run keeps the Task busy: queued, not yet delivered.
diff --git a/packages/web/e2e/steer-reload.spec.mjs b/packages/web/e2e/steer-reload.spec.mjs
index f2cc32d4..377ce9a0 100644
--- a/packages/web/e2e/steer-reload.spec.mjs
+++ b/packages/web/e2e/steer-reload.spec.mjs
@@ -56,7 +56,7 @@ test("a steered message survives reload as a queued hint with its content — no
await ta.waitFor();
await ta.fill("slow stream test");
await page.getByRole("button", { name: "发送" }).click();
- await expect(page.getByText("exec_command").first()).toBeVisible();
+ await expect(page.getByText("执行命令").first()).toBeVisible();
await page.getByRole("button", { name: "允许" }).click();
// Steer while the ~8s tool run keeps the Task busy (default mid-run mode is steer).
diff --git a/packages/web/e2e/subagent.spec.mjs b/packages/web/e2e/subagent.spec.mjs
index 8cf6e97c..c9a24c79 100644
--- a/packages/web/e2e/subagent.spec.mjs
+++ b/packages/web/e2e/subagent.spec.mjs
@@ -321,7 +321,7 @@ test("an approval inside the subagent stays discoverable via the chip badge and
// Open the panel from the chip and approve the child's tool call from inside it.
await pendingChip.click();
await expect(page.locator('[data-tab-id="agents"][data-active="true"]')).toBeVisible();
- await expect(page.getByText("exec_command").first()).toBeVisible();
+ await expect(page.getByText("执行命令").first()).toBeVisible();
await page.getByRole("button", { name: "允许" }).click();
// The child completes inside the panel, and the parent's turn then runs to completion.
diff --git a/packages/web/src/features/chat/tool-call-card.tsx b/packages/web/src/features/chat/tool-call-card.tsx
index 0a06ec2a..7cd231f4 100644
--- a/packages/web/src/features/chat/tool-call-card.tsx
+++ b/packages/web/src/features/chat/tool-call-card.tsx
@@ -17,6 +17,7 @@
import { useMemo, useRef, useState } from "react";
import { S } from "../../lib/strings";
import { humanizeDuration } from "../../lib/format";
+import { toolDisplayName } from "../../lib/tool-alias";
import { stripAnsi } from "../../lib/strip-ansi";
import { approvalKey } from "../../lib/omni/stream-model";
import type { ToolCallItem } from "../../lib/omni/stream-model";
@@ -33,6 +34,7 @@ import { StatusIcon } from "../../components/ui/status-icon";
import type { RunState } from "../../components/ui/status-icon";
import { ApprovalButtons } from "./approval-buttons";
import { LiveDuration } from "./live-duration";
+import { useTheme } from "../../state/theme";
import { agentIdFromRunSubagentArgs } from "./agent-topology";
import { SubagentChip } from "./subagent-chip";
import type { StreamRenderContext } from "./message-stream";
@@ -244,10 +246,19 @@ export function ToolCallCard({ item, ctx }: { item: ToolCallItem; ctx: StreamRen
const [open, setOpen] = useState(false);
const userToggled = useRef(false);
const rootRef = useRef<HTMLDivElement>(null);
+ const { toolAliases } = useTheme();
// Matched by the current origin chain + toolCallId: prevents parent/child session tool_call_id collisions from lighting each other up.
const pending = ctx.pendingApprovals.get(approvalKey(ctx.origin, item.toolCallId));
const preview = previewArguments(item.name, item.argumentsText);
+ // Display-only, and confined to the two render expressions below: every name-keyed
+ // decision on this card (DESCRIBED_TOOLS, FILE_TOOLS, the argument previews, the subagent
+ // chip) and everywhere else in the app (the tools config table, permission rules, the
+ // Trace viewer) keeps reading `item.name`, so an alias can never change what a call means.
+ const displayName = toolDisplayName(item.name, toolAliases);
+ // The tool's own name stays one hover away, for matching a Trace or writing a permission
+ // rule; when nothing was aliased the tooltip would only repeat the visible text.
+ const nameTitle = displayName === item.name ? undefined : item.name;
// Escape sequences are stripped at render time only (the stored stream/trace data keeps its
// raw bytes): hardened child envs should no longer produce any, but historical traces and
// force-color programs still can (#102). Memoized — the aggregated output can be large and
@@ -344,8 +355,11 @@ export function ToolCallCard({ item, ctx }: { item: ToolCallItem; ctx: StreamRen
className={`${DISCLOSURE_ROW_STICKY_CLASS} ${DISCLOSURE_ROW_CLASS}`}
>
<StatusIcon state={state} label={stateLabel} />
- <span className="shrink-0 truncate font-mono text-xs font-semibold text-gray-700 dark:text-gray-300">
- {item.name || S.chat.unknownTool}
+ <span
+ title={nameTitle}
+ className="shrink-0 truncate font-mono text-xs font-semibold text-gray-700 dark:text-gray-300"
+ >
+ {displayName || S.chat.unknownTool}
</span>
{/* Human-readable subtitle: the model-written call description (command/subagent tools) or the file path (file tools). */}
{subtitle && (
@@ -395,8 +409,11 @@ export function ToolCallCard({ item, ctx }: { item: ToolCallItem; ctx: StreamRen
this pending block unmounts and only the truncating header subtitle remains. At
≥sm the row stays one line (the desktop column is wide enough in practice). */}
<div className="mb-2 flex items-start gap-2 sm:items-center">
- <span className="shrink-0 rounded-md bg-white px-1.5 py-0.5 font-mono text-xs font-semibold text-gray-700 dark:bg-gray-900 dark:text-gray-300">
- {item.name || S.chat.unknownTool}
+ <span
+ title={nameTitle}
+ className="shrink-0 rounded-md bg-white px-1.5 py-0.5 font-mono text-xs font-semibold text-gray-700 dark:bg-gray-900 dark:text-gray-300"
+ >
+ {displayName || S.chat.unknownTool}
</span>
<span className="min-w-0 flex-1 whitespace-pre-wrap break-all font-mono text-xs text-gray-600 sm:truncate dark:text-gray-400">
{preview}
diff --git a/packages/web/src/features/settings/appearance-section.tsx b/packages/web/src/features/settings/appearance-section.tsx
index 819b3c92..fda07cf8 100644
--- a/packages/web/src/features/settings/appearance-section.tsx
+++ b/packages/web/src/features/settings/appearance-section.tsx
@@ -4,7 +4,9 @@
* there is no Save button. The terminal keeps its own theme row because plenty of people
* pin a dark terminal inside a light app; it follows the app unless pinned (see
* TerminalThemeMode). The workbench launcher's row is here rather than with the chat's own
- * settings because it is the same kind of choice: whether a piece of chrome is drawn.
+ * settings because it is the same kind of choice: whether a piece of chrome is drawn. The
+ * tool short-name row is here for the same reason — it changes how a tool call is spelled
+ * on screen, never what runs.
*/
import { useSyncExternalStore } from "react";
import { S } from "../../lib/strings";
@@ -30,6 +32,8 @@ export function AppearanceSection() {
setAccent,
terminalMode,
setTerminalMode,
+ toolAliases,
+ setToolAliases,
} = useTheme();
// The fan's "hide launcher" entry writes the same preference, so this row follows it.
useSyncExternalStore(subscribeLauncherHidden, launcherHiddenVersion);
@@ -69,6 +73,9 @@ export function AppearanceSection() {
<PrefRow label={S.settings.launcher} info={S.settings.launcherInfo}>
<Switch checked={launcherShown} onChange={(shown) => writeLauncherHidden(!shown)} />
</PrefRow>
+ <PrefRow label={S.settings.toolAliases} info={S.settings.toolAliasesInfo}>
+ <Switch checked={toolAliases} onChange={setToolAliases} />
+ </PrefRow>
</div>
);
}
diff --git a/packages/web/src/lib/install-scope.ts b/packages/web/src/lib/install-scope.ts
index eefb5b7b..087806e7 100644
--- a/packages/web/src/lib/install-scope.ts
+++ b/packages/web/src/lib/install-scope.ts
@@ -113,6 +113,12 @@ export const KEY_RULES: readonly KeyRule[] = [
scope: "browser",
why: "Display currency for prices; a formatting choice, prices are stored in USD either way.",
},
+ {
+ kind: "exact",
+ key: "penguin.toolAliases",
+ scope: "browser",
+ why: "Whether tool cards name the built-in tools by their short alias; a display choice of this browser, naming nothing on the server.",
+ },
{
kind: "exact",
key: "penguin.terminal.theme",
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index a6dc00ae..f59201be 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -183,6 +183,9 @@ export const en: Strings = {
launcher: "Shortcuts launcher",
launcherInfo:
"The round button floating on the conversation's right edge that fans out shortcuts to the workbench's panels and the terminal. Turning it off here removes it; the fan's \"Hide launcher\" entry does the same.",
+ toolAliases: "Tool short names",
+ toolAliasesInfo:
+ 'Tool cards in a conversation name the built-in tools by a short alias: read_file reads as "read". Every other tool (MCP tools included) and the Trace viewer keep the tool\'s own name, and hovering a short name shows it.',
currencyInfo: "Display currency for prices; storage is always USD.",
changePasswordInfo: "Change this account's sign-in password.",
accentNames: {
@@ -2048,6 +2051,20 @@ Scenarios:
return `failed${detail}, keeping current context`;
},
unknownTool: "(unknown tool)",
+ /**
+ * Short display names for the built-in tools, keyed by the name the model calls them
+ * by. The tool-call card shows these while the Appearance switch is on; a tool absent
+ * from this table (MCP tools, names only older Traces carry) renders as itself.
+ */
+ toolAliases: {
+ read_file: "read",
+ write_file: "write",
+ edit_file: "edit",
+ exec_command: "exec",
+ input_command: "follow",
+ run_subagent: "subagent",
+ input_subagent: "communicate",
+ } as Record<string, string>,
workRunning: "Running",
workDone: "Done",
workGroupSteps: (n: number) => `${n} ${n === 1 ? "step" : "steps"}`,
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index 8f189319..48549eb4 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -198,6 +198,9 @@ export const zh = {
launcher: "快捷方式悬浮球",
launcherInfo:
"在对话正文右缘浮动的圆形按钮,展开后是工作台各块面板与终端的快捷方式;这里关掉后它就不再出现,展开里的「隐藏悬浮球」同样会关掉它。",
+ toolAliases: "工具短名",
+ toolAliasesInfo:
+ "对话里的工具卡片用短名称呼内置工具,read_file 显示为「读取」。其余工具(含 MCP 工具)与轨迹观测始终是工具原本的名字;悬停短名也能看到它。",
currencyInfo: "价格显示币种;存储始终为美元。",
changePasswordInfo: "更改当前账号的登录密码。",
accentNames: {
@@ -2024,6 +2027,20 @@ Benchmark:
return `失败${detail},保留当前上下文`;
},
unknownTool: "(未知工具)",
+ /**
+ * Short display names for the built-in tools, keyed by the name the model calls them
+ * by. The tool-call card shows these while the Appearance switch is on; a tool absent
+ * from this table (MCP tools, names only older Traces carry) renders as itself.
+ */
+ toolAliases: {
+ read_file: "读取",
+ write_file: "写入",
+ edit_file: "编辑",
+ exec_command: "执行命令",
+ input_command: "跟进命令",
+ run_subagent: "子智能体",
+ input_subagent: "交流",
+ } as Record<string, string>,
workRunning: "运行中",
workDone: "运行完毕",
workGroupSteps: (n: number) => `${n} 步`,
diff --git a/packages/web/src/lib/tool-alias.ts b/packages/web/src/lib/tool-alias.ts
new file mode 100644
index 00000000..36c2c8bd
--- /dev/null
+++ b/packages/web/src/lib/tool-alias.ts
@@ -0,0 +1,24 @@
+/**
+ * Short display names for the built-in tools, shown on the chat's tool-call card in place
+ * of the name the model calls them by, while the Appearance switch is on.
+ *
+ * Display-only, and that boundary is load-bearing: the tool name keys real behaviour all
+ * over the app — which tools carry a `description` argument, which are previewed by a file
+ * path, which spawns a subagent, the Agent settings tools table (where the name IS the
+ * config key), and the permission rules a user writes. Resolve a name through this helper
+ * at the render expression only; an alias must never reach a comparison or a lookup key.
+ *
+ * Only the built-in tools have an entry. An MCP tool (always `mcp__<server>__<tool>`) and
+ * the names only older Traces still carry (`kill_command`, `read_image`, `describe_image`,
+ * `kill_subagent`) render exactly as they are, in either switch position.
+ */
+import { S } from "./strings";
+
+/**
+ * How a tool call is named on screen: the short alias when the reader has them on and the
+ * tool is one of the built-ins, the tool's own name otherwise.
+ */
+export function toolDisplayName(name: string, aliased: boolean): string {
+ if (!aliased) return name;
+ return S.chat.toolAliases[name] ?? name;
+}
diff --git a/packages/web/src/state/theme.tsx b/packages/web/src/state/theme.tsx
index 2b8c700b..04b70443 100644
--- a/packages/web/src/state/theme.tsx
+++ b/packages/web/src/state/theme.tsx
@@ -6,6 +6,8 @@
* - Font size: scales the root font-size (rem-based text-* utilities scale along with it).
* - Theme color: html[data-accent] overrides --accent-bg/--accent-fg; defaults to neutral
* (gray/white, follows light/dark).
+ * - Tool short names: whether a tool-call card names the built-in tools by a short alias
+ * instead of the name the model calls them by. Display-only, default on.
* - Terminal theme: its own light/dark/follow-the-app setting, following the app unless
* explicitly pinned — see TerminalThemeMode. It drives no class or variable here; the
* terminal reads `terminalDark` and paints itself, because Tailwind's dark: variant is
@@ -36,6 +38,7 @@ const FONT_KEY = "penguin.fontScale";
const ACCENT_KEY = "penguin.accent";
const CURRENCY_KEY = "penguin.currency";
const TERMINAL_KEY = "penguin.terminal.theme";
+const TOOL_ALIASES_KEY = "penguin.toolAliases";
/** Font size tier → root font-size (px): overall slightly larger than the system default for readability. */
const FONT_PX: Record<FontScale, string> = { sm: "16px", md: "18px", lg: "20px" };
@@ -54,6 +57,9 @@ interface ThemeContextValue {
setCurrency: (currency: Currency) => void;
terminalMode: TerminalThemeMode;
setTerminalMode: (mode: TerminalThemeMode) => void;
+ /** Whether tool-call cards name the built-in tools by their short alias. */
+ toolAliases: boolean;
+ setToolAliases: (on: boolean) => void;
/** Resolved terminal appearance ("app" already resolved against the app's own). */
terminalDark: boolean;
}
@@ -93,6 +99,11 @@ function initialTerminalMode(): TerminalThemeMode {
return "app";
}
+/** Default on, so anything but the explicit off value reads as on (an absent value included). */
+function initialToolAliases(): boolean {
+ return localStorage.getItem(TOOL_ALIASES_KEY) !== "0";
+}
+
function initialCurrency(): Currency {
return localStorage.getItem(CURRENCY_KEY) === "CNY" ? "CNY" : "USD";
}
@@ -108,6 +119,7 @@ export function ThemeProvider({ children }: { children: ReactNode }) {
const [accent, setAccentState] = useState<Accent>(initialAccent);
const [currency, setCurrencyState] = useState<Currency>(initialCurrency);
const [terminalMode, setTerminalModeState] = useState<TerminalThemeMode>(initialTerminalMode);
+ const [toolAliases, setToolAliasesState] = useState<boolean>(initialToolAliases);
const dark = mode === "system" ? sysDark : mode === "dark";
const terminalDark = terminalMode === "app" ? dark : terminalMode === "dark";
@@ -161,6 +173,11 @@ export function ThemeProvider({ children }: { children: ReactNode }) {
setTerminalModeState(next);
}, []);
+ const setToolAliases = useCallback((next: boolean) => {
+ localStorage.setItem(TOOL_ALIASES_KEY, next ? "1" : "0");
+ setToolAliasesState(next);
+ }, []);
+
return (
<ThemeContext.Provider
value={{
@@ -176,6 +193,8 @@ export function ThemeProvider({ children }: { children: ReactNode }) {
terminalMode,
setTerminalMode,
terminalDark,
+ toolAliases,
+ setToolAliases,
}}
>
{children}
diff --git a/packages/web/test/tool-alias.test.ts b/packages/web/test/tool-alias.test.ts
new file mode 100644
index 00000000..39736453
--- /dev/null
+++ b/packages/web/test/tool-alias.test.ts
@@ -0,0 +1,85 @@
+/**
+ * tool-alias.ts unit tests: resolving a tool call's display name.
+ *
+ * The table covers the built-in tools and nothing else — an MCP tool and the names only
+ * older Traces still carry must survive both switch positions untouched, and turning the
+ * switch off must hand back every name exactly as it came in.
+ *
+ * Which tools those are is taken from core's own registry rather than from a list repeated
+ * here, so registering an eighth built-in tool without giving it a short name fails this
+ * file instead of silently shipping one card that still reads as the model's wire name.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import { BUILTIN_TOOL_FACTORIES } from "@prismshadow/penguin-core";
+import { setActiveStrings, zh } from "../src/lib/strings";
+import { en } from "../src/lib/strings-en";
+import { toolDisplayName } from "../src/lib/tool-alias";
+
+/** Wire name -> alias, in the active language. */
+const EN_ALIASES: Record<string, string> = {
+ read_file: "read",
+ write_file: "write",
+ edit_file: "edit",
+ exec_command: "exec",
+ input_command: "follow",
+ run_subagent: "subagent",
+ input_subagent: "communicate",
+};
+
+const ZH_ALIASES: Record<string, string> = {
+ read_file: "读取",
+ write_file: "写入",
+ edit_file: "编辑",
+ exec_command: "执行命令",
+ input_command: "跟进命令",
+ run_subagent: "子智能体",
+ input_subagent: "交流",
+};
+
+/** Names that must pass through: an MCP tool, and tools no longer assembled but still in old Traces. */
+const PASSTHROUGH = [
+ "mcp__playwright__browser_click",
+ "mcp__github__create_issue",
+ "kill_command",
+ "read_image",
+ "describe_image",
+ "kill_subagent",
+];
+
+afterEach(() => setActiveStrings(zh));
+
+describe("toolDisplayName", () => {
+ it("names each built-in tool by its alias, in either language", () => {
+ setActiveStrings(en);
+ for (const [name, alias] of Object.entries(EN_ALIASES)) {
+ expect(toolDisplayName(name, true)).toBe(alias);
+ }
+ setActiveStrings(zh);
+ for (const [name, alias] of Object.entries(ZH_ALIASES)) {
+ expect(toolDisplayName(name, true)).toBe(alias);
+ }
+ });
+
+ it("passes MCP tools and historical names through with the switch on", () => {
+ for (const name of PASSTHROUGH) {
+ expect(toolDisplayName(name, true)).toBe(name);
+ }
+ setActiveStrings(en);
+ for (const name of PASSTHROUGH) {
+ expect(toolDisplayName(name, true)).toBe(name);
+ }
+ });
+
+ it("returns every name unchanged with the switch off", () => {
+ for (const name of [...Object.keys(ZH_ALIASES), ...PASSTHROUGH, ""]) {
+ expect(toolDisplayName(name, false)).toBe(name);
+ }
+ });
+
+ it("aliases exactly core's built-in tools, in both dictionaries", () => {
+ const builtins = Object.keys(BUILTIN_TOOL_FACTORIES).sort();
+ expect(builtins).toEqual(Object.keys(EN_ALIASES).sort());
+ expect(Object.keys(zh.chat.toolAliases).sort()).toEqual(builtins);
+ expect(Object.keys(en.chat.toolAliases).sort()).toEqual(builtins);
+ });
+});