Say what a tool did, not where it ran

An agent event set its label to the SSH profile's name, so the transcript read
"homeserver · ls -la" -- naming the machine rather than the thing that was done.
Built-in tools set no label at all and fell back to the function name, so a
saved memory read "memory_add". The status line said "Running shell_run…" and
the approval card had its own hand-written wording. Four places, four answers,
nothing checking that any of them agreed.

services/tool_labels.py is the one table all of them read now. Bash, Read,
Write, List, Web search, Memory saved; an icon each, instead of everything
being the sparkle.

The precedence is inverted on purpose. Tool events are persisted in
Message.tool_calls_json, so every agent row already on disk carries the profile
name -- a resolver that preferred the stored value would fix nothing for any
transcript that already exists. So a name the table knows resolves from the
table, and a name it does not -- a custom HTTP tool, an MCP tool, whose labels
are per row and cannot be tabulated -- keeps its own. One rule, both cases
correct. The machine moves to `detail`, where "where this ran" belongs.

tool_label and tool_icon are Jinja globals because a message bubble is rendered
from four handlers, and a fifth thing each of them must remember to pass is a
fifth thing one of them will forget.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/lembas/services/agent/tools.py

@@ -42,16 +42,31 @@ FAMILY_AGENT = "agent"
 # stored on every message forever.
 MAX_EVENT_CHARS = 4000
 
+# And how much of a diff. Same reasoning as the constant above and the same
+# ceiling in spirit: a generated file's diff can be larger than the file, and
+# this one is stored on the row forever and re-parsed on every page load.
+MAX_DIFF_LINES = 200
+
 _STRING = {"type": "string"}
 
 
 def _event(name: str, context: AgentContext, summary: str, **extra: Any) -> dict[str, Any]:
+    """One line in the transcript for one call.
+
+    No `label`. What a tool is called is decided by `services/tool_labels.py`,
+    for every tool at once -- this used to write the SSH profile's name here, so
+    a bubble said "homeserver · ls -la" and named the machine rather than the
+    thing that was done. The machine is a fact about *where*, so it belongs with
+    the directory in `detail`, which the template already renders in the body.
+    """
+    where = context.label
+    if context.project_dir:
+        where = f"{where}:{context.project_dir}"
     return {
         "name": name,
         "kind": "agent",
-        "label": f"{context.label}",
         "query": summary,
-        "detail": context.project_dir or "",
+        "detail": where,
         "results": [],
         **extra,
     }

src/lembas/services/generation.py

@@ -30,7 +30,7 @@ from lembas.db.models import KIND_AGENT, ROLE_ASSISTANT, ROLE_USER, Chat, Messag
 from lembas.db.session import session_scope
 from lembas.services import chat as chat_service
 from lembas.services import compaction as compaction_service
-from lembas.services import interaction, tokens
+from lembas.services import interaction, tokens, tool_labels
 from lembas.services import metrics as metrics_service
 from lembas.services import prompts as prompts_service
 from lembas.services import tools as tools_service
@@ -721,6 +721,26 @@ def _gave_up(generation, why: str) -> None:
     generation.touch()
 
 
+def _written(generation: Generation) -> int:
+    """How much this reply has written so far, in tokens, reported or estimated.
+
+    Both, because neither alone is enough. `completion_tokens` is only populated
+    when the endpoint sends a usage block, and a good half of the ones this
+    talks to -- llama.cpp, Ollama and friends -- never do; the fallback estimate
+    is otherwise computed once, in `_run`'s `finally:`, long after the loop that
+    needs it. A ceiling reading only the reported figure would work on OpenAI
+    and silently do nothing everywhere else, which is the worst kind of limit:
+    one that looks configured.
+
+    Reasoning counts. It was generated and it was paid for, even though it is
+    deliberately never replayed as context.
+    """
+    return max(
+        generation.completion_tokens,
+        tokens.estimate(generation.text + generation.thinking),
+    )
+
+
 def _tool_status(calls: list[dict]) -> str:
     """What to show while tools run.
 
@@ -728,7 +748,7 @@ def _tool_status(calls: list[dict]) -> str:
     nothing streaming, and a silent pause is exactly what a hang looks like.
     """
     if len(calls) == 1:
-        return f"Running {calls[0]['name']}…"
+        return f"Running {tool_labels.label_for(calls[0]['name'])}…"
     return f"Running {len(calls)} tools…"
 
 
@@ -746,17 +766,12 @@ def _describe(name: str, args: dict) -> tuple[str, str]:
     The detail is the thing being agreed to -- the command line, the path -- and
     is shown verbatim and escaped. A summary that paraphrased it would be a card
     approving something other than what runs.
+
+    Delegated to services/tool_labels.py, which the transcript and the status
+    line read too. This used to be a hand-written if-chain and was the fourth
+    place with its own wording for the same tool.
     """
-    if name == "shell_run":
-        return "Run a command", str(args.get("command") or "")
-    if name == "file_write":
-        return "Write a file", str(args.get("path") or "")
-    if name == "file_read":
-        return "Read a file", str(args.get("path") or "")
-    if name == "file_list":
-        return "List a directory", str(args.get("path") or "")
-    detail = ", ".join(f"{k}={v!r}" for k, v in list(args.items())[:4])
-    return f"Use {name}", detail[:400]
+    return tool_labels.describe(name, args)
 
 
 def _approvals(context, calls: list[dict]) -> list[interaction.Item]:

src/lembas/services/tool_labels.py

@@ -0,0 +1,208 @@
+"""What a tool is called in the interface, and what it looks like.
+
+Four places have to agree about one tool, and for the whole life of the feature
+they did not:
+
+- the transcript (`chat/_tool_activity.html`) showed the SSH profile's name for
+  an agent tool -- "homeserver · ls -la", naming the machine rather than the
+  thing that was done -- and the raw function name for everything else, so a
+  saved memory read `memory_add`;
+- the status line while a round runs said "Running shell_run…";
+- the approval card had its own hand-written if-chain;
+- and nothing checked that any of the three matched.
+
+So the table lives here and each of them reads it.
+
+`LABELS` and `ACTIONS` are deliberately different words for the same tool, the
+same way `policy.MODE_HINTS` and `policy.MODE_GUIDANCE` are. A label is a noun
+phrase in a list of things that happened; an approval card is a sentence
+somebody is agreeing to, and "Bash" is not one.
+
+**The precedence is inverted on purpose, and that is the whole design.**
+Tool events are persisted in `Message.tool_calls_json`, so every row written
+before today already carries `label: "homeserver"`. A resolver that preferred
+the stored label would fix nothing for any transcript that already exists. So
+a name this module knows about resolves from the static table and the stored
+label is ignored; a name it does not know -- a custom HTTP tool, an MCP tool,
+whose labels are per row and cannot be tabulated -- keeps its own. One rule,
+both cases correct.
+
+Resolved **without a database**. It is called once per rendered event, and
+reaching for `tools.registry(db)` from a Jinja global would be two table scans
+per bubble.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# What the transcript calls each tool. Kept in the same order as the families
+# in `services/tools.py` so that adding one has an obvious home.
+LABELS: dict[str, str] = {
+    # Acting on the machine an agent chat is pointed at.
+    "shell_run": "Bash",
+    "file_read": "Read",
+    "file_write": "Write",
+    "file_edit": "Update",
+    "file_list": "List",
+    "plan_submit": "Plan",
+    "plan_update": "Plan updated",
+    # The web.
+    "web_search": "Web search",
+    "fetch": "Fetch",
+    # The library.
+    "knowledge_search": "Knowledge searched",
+    "knowledge_get": "Document read",
+    "notes_search": "Notes searched",
+    "notes_get": "Note read",
+    "notes_create": "Note written",
+    "notes_edit": "Note updated",
+    "notes_delete": "Note deleted",
+    "memory_add": "Memory saved",
+    "memory_forget": "Memory removed",
+    "skill_get": "Skill read",
+    "skill_create": "Skill written",
+    "skill_edit": "Skill updated",
+    # Stopping to ask.
+    "ask_user": "Asked you",
+}
+
+# A symbol id from templates/partials/icons.html. Everything used to be the
+# sparkle, which said only "a model did something".
+ICONS: dict[str, str] = {
+    "shell_run": "terminal",
+    "file_read": "file-text",
+    "file_write": "pencil",
+    "file_edit": "diff",
+    "file_list": "folder",
+    "plan_submit": "check",
+    "plan_update": "check",
+    "web_search": "globe",
+    "fetch": "link",
+    "knowledge_search": "archive",
+    "knowledge_get": "file-text",
+    "notes_search": "search",
+    "notes_get": "file-text",
+    "notes_create": "pencil",
+    "notes_edit": "pencil",
+    "notes_delete": "trash",
+    "memory_add": "star",
+    "memory_forget": "trash",
+    "skill_get": "sparkle",
+    "skill_create": "sparkle",
+    "skill_edit": "sparkle",
+    "ask_user": "chat",
+}
+
+# The icon for an event whose tool is not in the table -- a custom HTTP tool, an
+# MCP tool, or a row written before `kind` existed.
+KIND_ICONS: dict[str, str] = {
+    "search": "globe",
+    "fetch": "link",
+    "custom": "link",
+    "mcp": "server",
+}
+FALLBACK_ICON = "sparkle"
+
+# What an approval card is headed. A sentence somebody agrees to, in the
+# imperative, because that is what pressing the button does.
+ACTIONS: dict[str, str] = {
+    "shell_run": "Run a command",
+    "file_read": "Read a file",
+    "file_write": "Write a file",
+    "file_edit": "Update a file",
+    "file_list": "List a directory",
+    "web_search": "Search the web",
+    "fetch": "Fetch a page",
+    "knowledge_search": "Search the library",
+    "knowledge_get": "Read a document",
+    "notes_search": "Search notes",
+    "notes_get": "Read a note",
+    "notes_create": "Write a note",
+    "notes_edit": "Change a note",
+    "notes_delete": "Delete a note",
+    "memory_add": "Remember something",
+    "memory_forget": "Forget something",
+    "skill_get": "Read a skill",
+    "skill_create": "Write a skill",
+    "skill_edit": "Change a skill",
+}
+
+# Which argument is the thing being agreed to. Shown verbatim and escaped on the
+# card: a summary that paraphrased it would be a card approving something other
+# than what runs.
+DETAIL_KEYS: dict[str, str] = {
+    "shell_run": "command",
+    "file_read": "path",
+    "file_write": "path",
+    "file_edit": "path",
+    "file_list": "path",
+    "fetch": "url",
+    "web_search": "query",
+    "knowledge_search": "query",
+    "notes_search": "query",
+}
+
+
+def _name_of(event: dict[str, Any] | str) -> str:
+    if isinstance(event, str):
+        return event
+    return str(event.get("name") or "")
+
+
+def label_for(event: dict[str, Any] | str) -> str:
+    """What to call this tool in the transcript.
+
+    The static table wins over anything stored on the event. See the module
+    docstring: rows already on disk carry the wrong label, and deferring to them
+    would leave every existing transcript naming a machine.
+    """
+    name = _name_of(event)
+    if name in LABELS:
+        return LABELS[name]
+    if isinstance(event, dict):
+        stored = str(event.get("label") or "").strip()
+        if stored:
+            return stored
+    return name
+
+
+def icon_for(event: dict[str, Any] | str) -> str:
+    """A symbol id for this event, never empty.
+
+    Falls through the tool's own icon, then the event's `kind`, then the
+    generic one -- so a custom tool still gets a link and an MCP tool a server,
+    which is what the template used to decide for itself.
+    """
+    name = _name_of(event)
+    if name in ICONS:
+        return ICONS[name]
+    kind = str(event.get("kind") or "") if isinstance(event, dict) else ""
+    if not kind and name == "web_search":
+        # Rows written before `kind` existed. The template made the same
+        # allowance for the same reason.
+        kind = "search"
+    return KIND_ICONS.get(kind, FALLBACK_ICON)
+
+
+def describe(name: str, args: dict[str, Any]) -> tuple[str, str]:
+    """What an approval card says about one call: a title, and the detail."""
+    title = ACTIONS.get(name)
+    key = DETAIL_KEYS.get(name)
+    if title is not None:
+        return title, str(args.get(key) or "") if key else ""
+    detail = ", ".join(f"{k}={v!r}" for k, v in list(args.items())[:4])
+    return f"Use {label_for(name)}", detail[:400]
+
+
+__all__ = [
+    "ACTIONS",
+    "DETAIL_KEYS",
+    "FALLBACK_ICON",
+    "ICONS",
+    "KIND_ICONS",
+    "LABELS",
+    "describe",
+    "icon_for",
+    "label_for",
+]

src/lembas/web/templates/chat/_tool_activity.html

@@ -19,23 +19,24 @@
   `kind` says how to label the event. Rows written before it existed have none,
   so web_search reads as a search and everything else falls to the generic
   branch: an old notes_search event used to claim it had searched the web.
+
+  What a tool is *called* is not decided here. `tool_label` and `tool_icon` are
+  Jinja globals over services/tool_labels.py, which is the one table the status
+  line and the approval card read too. It deliberately ignores an `event.label`
+  it recognises the name of: rows already on disk carry the SSH profile's name,
+  so a resolver that preferred the stored value would leave every existing
+  transcript saying "homeserver" where it means "Bash".
 #}
 {% for event in tool_events %}
 {% set kind = event.kind or ('search' if event.name == 'web_search' else 'tool') %}
 <details class="tool-activity {{ 'tool-activity--error' if event.status == 'error' }}">
   <summary class="tool-activity__summary">
-    {% if kind == 'search' %}
-      {{ icon("globe", "icon--sm tool-activity__icon") }}
-    {% elif kind == 'custom' %}
-      {{ icon("link", "icon--sm tool-activity__icon") }}
-    {% elif kind == 'mcp' %}
-      {{ icon("server", "icon--sm tool-activity__icon") }}
-    {% else %}
-      {{ icon("sparkle", "icon--sm tool-activity__icon") }}
-    {% endif %}
+    {{ icon(tool_icon(event), "icon--sm tool-activity__icon") }}
 
     <span class="tool-activity__label">
       {% if kind == 'search' %}
+        {# Prose, not "Web search · mallorn". A search is the one thing here
+           common enough to be worth a sentence. #}
         {% if event.status == "error" %}
           Web search failed
         {% elif event.query %}
@@ -44,7 +45,7 @@
           Searched the web
         {% endif %}
       {% else %}
-        {% set label = event.label or event.name %}
+        {% set label = tool_label(event) %}
         {% if event.status == "error" %}
           {{ label }} failed
         {% else %}

src/lembas/web/templates/partials/icons.html

@@ -195,6 +195,12 @@
     <path d="M13.5 3.5V9H19M8.5 13h7M8.5 16.5h7"/>
   </symbol>
 
+  <!-- Changing part of a file. A plus over a minus, which is what a diff looks
+       like everywhere else; the pencil is already taken by writing one whole. -->
+  <symbol id="i-diff" viewBox="0 0 24 24">
+    <path d="M12 3.5v7M8.5 7h7M8.5 17h7"/>
+  </symbol>
+
   <!-- A drag handle. Dots rather than lines: lines at this size read as a
        hamburger, which means something else entirely. -->
   <symbol id="i-grip" viewBox="0 0 24 24">

src/lembas/web/templating.py

@@ -12,6 +12,7 @@ from lembas import __version__
 from lembas.config import settings
 from lembas.db.models import User
 from lembas.services import metrics as metrics_service
+from lembas.services import tool_labels
 from lembas.services.markdown import highlight_tokens
 from lembas.services.reasoning import format_duration
 
@@ -51,6 +52,14 @@ templates.env.filters["stable_hue"] = stable_hue
 # every one of them would otherwise have to remember to pass it.
 templates.env.filters["tokens"] = highlight_tokens
 
+# What a tool call is called and what it looks like. Globals rather than
+# context values because a message bubble is rendered from four different
+# handlers -- pages, post_message, regenerate and the SSE follower -- and every
+# one of them would otherwise have to remember to pass them. That is the exact
+# trap `audio_service.template_flags` fell into.
+templates.env.globals["tool_label"] = tool_labels.label_for
+templates.env.globals["tool_icon"] = tool_labels.icon_for
+
 
 def resolve_theme(user: User | None) -> str:
     """Theme to render with on the server.