fix: address PR review feedback on tool dispatch sync

Author: clean6378-max-it

CONTRIBUTING.md

@@ -145,11 +145,12 @@ See [`docs/architecture.md`](docs/architecture.md) for data flow, export state m
 
 Claude Code assistant `tool_use` blocks carry a `name` string (e.g. `"Read"`, `"Bash"`). The browser coordinates that name across four sites; drift is caught by `tests/test_tool_dispatch_sync.py`.
 
-1. **`utils/tool_dispatch.py`** — add the name to `KNOWN_TOOL_TYPE_NAMES` (keep alphabetical). Set `_FILE_ACTIVITY_HANDLERS[name]` to a tracker function or `None`. If the tool has a distinct `toolUseResult` JSON shape, add `(predicate, builder)` to `_TOOL_RESULT_DISPATCH` (respect ordering — see module docstring and `tests/test_tool_dispatch_ordering.py`).
-2. **`utils/md_exporter.py`** — add an `elif name == "…"` branch in `_render_tool_use` and include the name in `MD_EXPORTER_TOOL_TYPES`.
-3. **`static/js/render/registry.js`** — add a `TOOL_USE_RENDERERS` entry (and a `tool_use/*.js` renderer module).
-4. **Optional result UI** — if the backend emits a new `result_type`, add `TOOL_RESULT_RENDERERS` and a `tool_result/*.js` module.
-5. Run `pytest tests/test_tool_dispatch_sync.py -v` — failure names the site missing the new type.
+1. **`utils/tool_dispatch.py`** — add the name to `_FILE_ACTIVITY_HANDLERS` (`None` if no file/bash/web side effects); `KNOWN_TOOL_TYPES` is derived from its keys. If the tool has a distinct `toolUseResult` JSON shape, add `(predicate, builder)` to `_TOOL_RESULT_DISPATCH` (respect ordering — see module docstring and `tests/test_tool_dispatch_ordering.py`).
+2. **`models/tool_results.py`** — add the name to `ToolNameLiteral` and, when the tool has a distinct result payload, add the TypedDict, type guard (`is_*_tool_result`), and union member on `ToolResultUnion`.
+3. **`utils/md_exporter.py`** — add an `elif name == "…"` branch in `_render_tool_use` and include the name in `MD_EXPORTER_TOOL_TYPES`.
+4. **`static/js/render/registry.js`** — add a `TOOL_USE_RENDERERS` entry (and a `tool_use/*.js` renderer module).
+5. **Optional result UI** — if the backend emits a new `result_type`, add `TOOL_RESULT_RENDERERS` and a `tool_result/*.js` module.
+6. Run `pytest tests/test_tool_dispatch_sync.py -v` — failure names the site missing the new type.
 
 ## Getting help
 

tests/test_tool_dispatch_sync.py

@@ -51,16 +51,22 @@ def _format_set_diff(expected: frozenset[str], actual: frozenset[str], site: str
     [
         ("utils/tool_dispatch.py (FILE_ACTIVITY_TOOL_TYPES)", FILE_ACTIVITY_TOOL_TYPES),
         ("utils/md_exporter.py (MD_EXPORTER_TOOL_TYPES)", MD_EXPORTER_TOOL_TYPES),
-        (
-            "static/js/render/registry.js (TOOL_USE_RENDERERS)",
-            _parse_frontend_tool_use_renderers(_FRONTEND_REGISTRY),
-        ),
     ],
 )
 def test_tool_type_sets_match_known_registry(site: str, actual: frozenset[str]) -> None:
     if actual != KNOWN_TOOL_TYPES:
         pytest.fail(_format_set_diff(KNOWN_TOOL_TYPES, actual, site))
 
 
+def test_frontend_registry_matches_known_tool_types() -> None:
+    site = "static/js/render/registry.js (TOOL_USE_RENDERERS)"
+    try:
+        actual = _parse_frontend_tool_use_renderers(_FRONTEND_REGISTRY)
+    except ValueError as exc:
+        pytest.fail(f"{site}: {exc}")
+    if actual != KNOWN_TOOL_TYPES:
+        pytest.fail(_format_set_diff(KNOWN_TOOL_TYPES, actual, site))
+
+
 def test_known_tool_types_nonempty() -> None:
     assert KNOWN_TOOL_TYPES

utils/jsonl_parser.py

@@ -388,5 +388,3 @@ def _process_progress(entry: dict[str, Any], messages: list[MessageDict]) -> Non
             "is_sidechain": entry.get("isSidechain", False),
         }
     )
-
-

utils/md_exporter.py

@@ -8,7 +8,6 @@
 from models.stats import SessionStatsDict
 from utils.jsonl_helpers import strip_system_tags
 from utils.session_stats import format_duration
-from utils.tool_dispatch import KNOWN_TOOL_TYPES
 
 
 def session_to_markdown(session: SessionDict, stats: SessionStatsDict | None = None) -> str:
@@ -324,8 +323,8 @@ def _render_tool_use(tool: ToolUseDict) -> str:
                     continue
                 lines.append(f">\n> Q: {q.get('question', '')}")
     else:
-        label = "Input" if name in KNOWN_TOOL_TYPES else "Input (unknown tool type)"
-        lines.append(f">\n> {label}: `{str(inp)}`")
+        # Unknown names, or known types listed in MD_EXPORTER_TOOL_TYPES before an elif exists.
+        lines.append(f">\n> Input (unknown tool type): `{str(inp)}`")
 
     return "\n".join(lines)
 

utils/tool_dispatch.py

@@ -18,13 +18,15 @@
 
 Adding a new Claude Code **tool use** name (e.g. ``"Read"``, ``"Bash"``):
 
-1. Add the name to ``KNOWN_TOOL_TYPE_NAMES`` below (alphabetical order).
-2. Wire ``_FILE_ACTIVITY_HANDLERS`` (``None`` if no file/bash/web side effects).
+1. Add the name to ``_FILE_ACTIVITY_HANDLERS`` below (``None`` if no file/bash/web
+   side effects); ``KNOWN_TOOL_TYPES`` is derived from its keys.
+2. Add the name to ``ToolNameLiteral`` in ``models/tool_results.py`` and, if the
+   tool has a distinct ``toolUseResult`` JSON shape, add the TypedDict, predicate,
+   and ``(predicate, builder)`` pair in ``_TOOL_RESULT_DISPATCH`` (respect ordering
+   — see notes above and ``tests/test_tool_dispatch_ordering.py``).
 3. Add a Markdown branch in ``utils/md_exporter.py`` ``_render_tool_use``.
 4. Add ``TOOL_USE_RENDERERS`` entry in ``static/js/render/registry.js``.
-5. Add ``(predicate, builder)`` to ``_TOOL_RESULT_DISPATCH`` when the tool has a
-   distinct ``toolUseResult`` shape (see ordering notes above).
-6. Run ``pytest tests/test_tool_dispatch_sync.py -v`` — it fails with the
+5. Run ``pytest tests/test_tool_dispatch_sync.py -v`` — it fails with the
    missing site if any step was skipped.
 
 See ``CONTRIBUTING.md`` § "Adding a new tool type".
@@ -235,20 +237,7 @@ def _tool_result_build_user_input(tr: ToolResultDict, base: dict[str, object]) -
 
 # Claude Code assistant tool_use ``name`` values coordinated across parser file
 # activity, Markdown export, and the SPA ``TOOL_USE_RENDERERS`` map.
-KNOWN_TOOL_TYPE_NAMES: tuple[str, ...] = (
-    "AskUserQuestion",
-    "Bash",
-    "Edit",
-    "Glob",
-    "Grep",
-    "Read",
-    "Task",
-    "TodoWrite",
-    "WebFetch",
-    "WebSearch",
-    "Write",
-)
-KNOWN_TOOL_TYPES: frozenset[str] = frozenset(KNOWN_TOOL_TYPE_NAMES)
+# ``_FILE_ACTIVITY_HANDLERS`` is the single registry; ``KNOWN_TOOL_TYPES`` is derived.
 
 
 def _file_activity_read(tool_input: dict[str, Any], metadata: dict[str, Any]) -> None:
@@ -284,7 +273,6 @@ def _file_activity_web(tool_input: dict[str, Any], metadata: dict[str, Any]) ->
         metadata["web_fetches"].append(url_or_query)
 
 
-# Every ``KNOWN_TOOL_TYPES`` entry must appear here (``None`` = no side effects).
 _FILE_ACTIVITY_HANDLERS: dict[str, Callable[[dict[str, Any], dict[str, Any]], None] | None] = {
     "AskUserQuestion": None,
     "Bash": _file_activity_bash,
@@ -298,6 +286,8 @@ def _file_activity_web(tool_input: dict[str, Any], metadata: dict[str, Any]) ->
     "WebSearch": _file_activity_web,
     "Write": _file_activity_write,
 }
+KNOWN_TOOL_TYPE_NAMES: tuple[str, ...] = tuple(sorted(_FILE_ACTIVITY_HANDLERS))
+KNOWN_TOOL_TYPES: frozenset[str] = frozenset(_FILE_ACTIVITY_HANDLERS)
 FILE_ACTIVITY_TOOL_TYPES: frozenset[str] = frozenset(_FILE_ACTIVITY_HANDLERS)