feat(tools): let the model name command runs via a title arg

[3Nya3]

What does this PR do?

terminal and execute_code gain an optional title arg (3-8 word human label). The gateway forwards it on tool.start, and the desktop + TUI prefer it over the deterministic command summary for pending, settled, group-summary, and approval rows - the exact spots where a long command like powershell -NoProfile -ExecutionPolicy Bypass -Command "..." is currently dumped raw into the row header. The model supplies the label at tool-call time, so this costs zero extra LLM calls (the aux-summarization approach was considered and rejected: extra call + latency + cost per approval).

A second, tightly coupled change in the same UX surface: compound-command summaries now name each segment (npx tsc · echo TSC-OK · npx vitest, + N more beyond three) instead of the opaque first + N commands that hid every segment after the first. Same files, same summarizer functions, same problem (unreadable command rows) - happy to split into a second PR if reviewers prefer.

Untitled runs keep today's behavior everywhere; the raw command always stays in the row detail/payload.

Related Issue

No tracking issue found. Prior art checked before building (per CONTRIBUTING search-first): PR #22363 (approval_purpose/effect/risk fields - structured risk context via a gateway follow-up message, different UX) and PR #68199 (Matrix-only async summary) are both open and complementary, not duplicates. This PR is the display-label counterpart at the row header.

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• tools/terminal_tool.py - optional title property in TERMINAL_SCHEMA (3-8 words, under 80 chars, prompted for long/wrapped commands)
• tools/code_execution_tool.py - same for the execute_code schema; _TOOL_STUBS sandbox stub updated to match (keeps TestStubSchemaDrift green)
• tui_gateway/server.py::_on_tool_start - forwards title on tool.start; the only window where pending/approval rows render before persisted args load
• apps/desktop/src/lib/chat-messages.ts - GatewayEventPayload.title documented for tool.start + forwarded into live tool args in toolArgs()
• apps/desktop/src/components/assistant-ui/tool/fallback-model/index.ts - pending row header prefers args.title (length-capped via existing compactPreview)
• apps/desktop/src/components/assistant-ui/tool/run-summary.ts - group/ticker line prefers title (new 80-char cap: model controls the string); settled titled commands stay named (Ran List Hermes processes) while untitled ones still collapse to Ran N commands
• ui-tui/src/app/createGatewayEventHandler.ts + gatewayTypes.ts - TUI shows the title in place of the command preview
• apps/desktop/src/lib/summarize-command.ts + agent/display.py - compound summaries name every segment (head sub per segment, ·-joined, + N more past three); both implementations kept in lockstep
• Tests: new coverage for every hop (schema drift, gateway forwarding, desktop args merge, label preference, title cap, compound naming, TUI handler)

How to Test

1. Start a new conversation (prompt-cache invariant: existing conversations keep the old schema)
2. Ask the agent to run a long wrapped command, or watch it emit title on its own for long commands
3. Observe: pending row shows Running <title>, settled row/group shows Ran <title>, and an approval prompt (with approvals.mode: manual) shows the title instead of the raw command
4. Run an untitled compound (node -v; npm -v; echo x): row reads node -v · npm -v · echo x
5. Untitled single commands and multi-tool groups render exactly as before

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(tools):)
• I searched for existing PRs to make sure this isn't a duplicate (feat: surface command context in approval prompts #22363, feat(matrix): compact approval cards with optional async summary #68199 - complementary, noted above)
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass (affected suites: gateway server, display, code-execution stub drift - all green; the ~18 tests/tools/ live-shell failures on this Windows machine reproduce identically on pristine origin/main and are pre-existing/environmental)
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Windows 11 (desktop app + CLI end-to-end; renderer labels verified live in the packed app)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) - N/A (tool schemas are the user-facing docs here and are updated; the website tools-reference has no per-arg tables)
• I've updated cli-config.yaml.example if I added/changed config keys - N/A (no config keys)
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows - N/A (no architecture change)
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide - pure string processing + one additive event field, no OS calls; scripts/check-windows-footguns.py --diff flags 15 pre-existing read_text() findings in tests/test_tui_gateway_server.py that are not added by this diff (0 flagged lines originate from this PR)
• I've updated tool descriptions/schemas if I changed tool behavior

Compatibility / prompt-cache notes

• Additive optional schema arg + additive event payload field: existing conversations keep their cached schema; old backends without the field degrade to today's labels; a title-emitting model against an old backend is harmless (handlers ignore unknown keys).

Screenshots / Logs

Verified live in the packed desktop app (Windows): titled settled row Ran List Hermes data directories 2.4s; titled group line Ran Show Hermes working tree status, used 1 tool; untitled compounds collapsed as Ran ls -la · powershell -NoProfile · tail -3 3.3s.

[spfcraze]

This was generated by AI during triage.

Summary:
For a compound member made up only of env assignments (FOO=1 && npm test), the new label step returns an empty string and the row renders · npm test.

Problems:

• _shell_segment_label (agent/display.py, new in this diff) skips every NAME=value word before taking the head; when every word is an env assignment the head and arg come back empty and the function returns "", so the join in summarize_shell_command renders a bare · slot. Running the new code against the origin/main helpers: FOO=1 && npm test → · npm test, where the previous tail rendered FOO=1 + 1 command.
• The desktop copy (segmentLabel, apps/desktop/src/lib/summarize-command.ts) is the same logic and shows the same empty slot.

Solution:
When the env-skip loop consumes every word, fall back to the cleaned segment (or its first word) so an env-only member still renders its own text.

---

Checked against b91e3fe — the tip of feat/command-run-titles when this was written — and ceebb21, main at the same moment.