Feature: configurable tool name truncation and wrap instead of hide on narrow terminals

[liao666brant]

Problem

When MCP tool names are long (e.g. mcp__plugin_context-mode_context-mode__ctx_batch_execute), the tools line takes up excessive horizontal space. On narrower terminals, this causes important information to be truncated or hidden entirely.

Example of the current behavior on a narrow terminal:

✓ Read ×4 | ✓ Bash ×2 | ✓ ToolSearch ×1 | ✓ mcp__plugin_context-mode_context-mode__ctx_batch_execute ×1

The long MCP name pushes the line far beyond typical terminal widths.

Proposed Solution

Add two new config options under display:

toolNameMaxLength (number, default: 0 = no limit)

Maximum display length for tool names. When exceeded, the name is truncated intelligently:

• For MCP-style names (mcp__xxx__tool_name), keep only the last segment (e.g. ctx_batch_execute)
• For other names, truncate with … suffix

toolsMaxVisible (number, default: 4, 0 = unlimited)

Maximum number of completed tool groups to display. Setting to 0 shows all tools, relying on the existing line-wrap mechanism to handle overflow.

Expected Behavior

With config:

{
  "display": {
    "showTools": true,
    "toolNameMaxLength": 20,
    "toolsMaxVisible": 0
  }
}

• mcp__plugin_context-mode_context-mode__ctx_batch_execute → ctx_batch_execute
• All completed tools are shown (not capped at 4)
• When terminal width is insufficient, tools wrap to the next line via the existing wrapLineToWidth mechanism instead of being hidden

Context

The existing wrapLineToWidth in render/index.ts already splits lines by | separators and wraps them. The missing pieces are:

1. No way to shorten long tool names before rendering
2. Hardcoded .slice(0, 4) limit on completed tools prevents showing all tools even when wrapping is available

[liao666brant]

Implementation Reference

I've prototyped this locally — here's the diff for reference:

1. src/config.ts — Add config fields

In HudConfig.display interface and DEFAULT_CONFIG.display:

// Interface
showTools: boolean;
toolNameMaxLength: number;  // 0 = no limit
toolsMaxVisible: number;    // 0 = unlimited, default 4
showAgents: boolean;

// DEFAULT_CONFIG
showTools: false,
toolNameMaxLength: 0,
toolsMaxVisible: 4,
showAgents: false,

In mergeConfig, validate as non-negative integers:

toolNameMaxLength: typeof migrated.display?.toolNameMaxLength === 'number'
  && Number.isFinite(migrated.display.toolNameMaxLength)
  && migrated.display.toolNameMaxLength >= 0
  ? Math.floor(migrated.display.toolNameMaxLength)
  : DEFAULT_CONFIG.display.toolNameMaxLength,
toolsMaxVisible: typeof migrated.display?.toolsMaxVisible === 'number'
  && Number.isFinite(migrated.display.toolsMaxVisible)
  && migrated.display.toolsMaxVisible >= 0
  ? Math.floor(migrated.display.toolsMaxVisible)
  : DEFAULT_CONFIG.display.toolsMaxVisible,

2. src/render/tools-line.ts — Apply truncation

export function renderToolsLine(ctx: RenderContext): string | null {
  const { tools } = ctx.transcript;
  const colors = ctx.config?.colors;
  const toolNameMaxLength = ctx.config?.display?.toolNameMaxLength ?? 0;
  const toolsMaxVisible = ctx.config?.display?.toolsMaxVisible ?? 4;

  if (tools.length === 0) return null;

  const parts: string[] = [];
  const runningTools = tools.filter((t) => t.status === 'running');
  const completedTools = tools.filter((t) => t.status === 'completed' || t.status === 'error');

  for (const tool of runningTools.slice(-2)) {
    const displayName = truncateToolName(tool.name, toolNameMaxLength);
    const target = tool.target ? truncatePath(tool.target) : '';
    parts.push(`${yellow('◐')} ${cyan(displayName)}${target ? label(`: ${target}`, colors) : ''}`);
  }

  const toolCounts = new Map<string, number>();
  for (const tool of completedTools) {
    toolCounts.set(tool.name, (toolCounts.get(tool.name) ?? 0) + 1);
  }

  const maxVisible = toolsMaxVisible === 0 ? Infinity : toolsMaxVisible;
  const sortedTools = Array.from(toolCounts.entries())
    .sort((a, b) => b[1] - a[1])
    .slice(0, maxVisible);

  for (const [name, count] of sortedTools) {
    const displayName = truncateToolName(name, toolNameMaxLength);
    parts.push(`${green('✓')} ${displayName} ${label(`×${count}`, colors)}`);
  }

  return parts.length > 0 ? parts.join(' | ') : null;
}

function truncateToolName(name: string, maxLength: number): string {
  if (maxLength <= 0 || name.length <= maxLength) return name;

  // For MCP-style names (mcp__plugin_xxx__tool_name), keep the last segment
  const mcpParts = name.split('__');
  if (mcpParts.length > 1) {
    const lastPart = mcpParts[mcpParts.length - 1];
    if (lastPart.length <= maxLength) return lastPart;
    return lastPart.slice(0, maxLength - 1) + '…';
  }

  return name.slice(0, maxLength - 1) + '…';
}

Key design decisions

• MCP name splitting by __: MCP tool names follow mcp__<server>__<tool> convention, so extracting the last segment gives the most meaningful short name
• toolsMaxVisible: 0 means unlimited: combined with the existing wrapLineToWidth in render/index.ts, this lets all tools display across multiple lines when the terminal is narrow
• No changes needed to the wrap logic: wrapLineToWidth already splits by | separators — it just needs more segments to be present in the tools line

Happy to open a PR if this direction looks good.

[jarrodwatts]

Thanks for writing this up and for including the prototype. I labelled this as an enhancement and the direction is reasonable, with a few constraints for a PR:

• Keep defaults unchanged: no truncation unless configured, and keep the existing completed-tools cap unless toolsMaxVisible is explicitly set.
• Validate both options as non-negative integers in config loading.
• Put the tool-name shortening behind a small helper with tests for MCP-style names, non-MCP names, very small max lengths, and duplicate/collision behavior.
• Preserve running-tool targets and existing path truncation.
• Add render tests for the default cap, toolsMaxVisible: 0, MCP last-segment display, ordinary truncation, and wrapped output.
• Update the README config table/docs.

I would keep this focused on the tools line. The broader MCP/Skills display requests in #516 and #527 can be handled separately so this stays easy to review.