claude-code-chat-browser: Tool dispatch coordination — single authoritative KNOWN_TOOL_TYPES registry

[clean6378-max-it]

Calendar Day

Tuesday, July 1, 2026 (PR 1 of 2)

Planned Effort

5 story points (Medium–High) — sprint item #3

Companion PR: Tuesday PR 2 (frontend tool registry #4) — stacks on or follows this PR; static/tool_types.json is generated from KNOWN_TOOL_TYPES established here.

Problem

Adding a new Claude Code tool type requires coordinated changes across four files (utils/tool_dispatch.py, file-activity tracking in utils/jsonl_parser.py, utils/md_exporter.py, and the frontend JS tool registry) with no compile-time or test-time mechanism to detect that one site was missed. The coupling is invisible to static analysis — sites are linked only by magic string literals ("Read", "Write", "Bash", etc.). The verification suite (466 tests) catches regressions in existing behavior but cannot enforce completeness when upstream Claude Code introduces a new tool type.

Goal

One merged PR that establishes a single authoritative KNOWN_TOOL_TYPES registry, wires all four dispatch sites to it, and adds a CI sync test that fails with a clear message when any site drifts.

Scope

Touch points

• utils/tool_dispatch.py — define KNOWN_TOOL_TYPES: frozenset[str] at module level; extract keys from _TOOL_RESULT_DISPATCH
• utils/jsonl_parser.py — file-activity tracking references KNOWN_TOOL_TYPES
• utils/md_exporter.py — exporter references KNOWN_TOOL_TYPES
• Frontend JS tool registry — references or is validated against KNOWN_TOOL_TYPES
• tests/test_tool_dispatch_sync.py (new) — parse frontend JS registry (regex or lightweight AST); assert set identical to KNOWN_TOOL_TYPES; failure names missing type and file
• CONTRIBUTING.md or inline docstring — document "add a new tool type" procedure

Out of scope

• Generated static/tool_types.json manifest (Tuesday PR 2 — #4)
• Schema drift detection (Thursday All core requirements from this issue are implemented and working. #5)
• file_activity hardcoded strings refactor (deferred)

Acceptance Criteria

• KNOWN_TOOL_TYPES is the single authoritative registry in utils/tool_dispatch.py
• All four dispatch sites import/reference this constant instead of independent string literals
• tests/test_tool_dispatch_sync.py asserts tool-type sets are identical across all four sites
• Sync test fails with a clear message naming the missing type and the file that lacks it
• Adding a type to the registry without updating all four sites causes test failure
• Documentation describes the "add a new tool type" procedure
• Full pytest, mypy --strict, and ruff pass
• PR approved by at least 1 reviewer

Verification

cd C:\Users\Jasen\CppAliance\claude-code-chat-browser
.\.venv\Scripts\Activate.ps1
pytest tests/test_tool_dispatch_sync.py -q
pytest -q
mypy .
ruff check .

Manual: deliberately remove a tool type from the frontend registry — confirm sync test fails with a clear message, then revert.