Merge pull request #101 from aaronsb/feat/multi-language

feat: multi-language support, agent tracking, adaptive TUI

Author: aaronsb

docs/architecture/system/ADR-107-way-match-corpus-batch-mode-and-locale-support.md

@@ -0,0 +1,69 @@
+# Multilingual Embedding Model Evaluation
+
+**Date:** 2026-04-03T04:07:51Z
+
+**Models:**
+- English: `all-MiniLM-L6-v2` (21M)
+- Multilingual: `paraphrase-multilingual-MiniLM-L12-v2` Q8_0 (127M)
+
+**Methodology:** Each test embeds a native-language prompt against both an English description (cross-language) and a native-language description (same-language stub scenario). Three scores per test:
+
+- **EN×EN**: English-only model, English description (baseline)
+- **Multi×EN**: multilingual model, English description (cross-language)
+- **Multi×Native**: multilingual model, native description (same-language stub)
+
+**Threshold:** 0.25 (same-language similarity minimum)
+
+## Results
+
+| Lang | Prompt | EN×EN | Multi×EN | Multi×Native | Pass |
+|:-----|:-------|------:|---------:|-------------:|:----:|
+| en | check dependencies for vulnerabilities | 0.7574 | 0.6822 | 0.6822 | ✅ |
+| de | Abhängigkeiten auf Schwachstellen prüfen | 0.0767 | 0.6223 | 0.8243 | ✅ |
+| es | verificar dependencias por vulnerabilidades | 0.4381 | 0.7893 | 0.8357 | ✅ |
+| fr | vérifier les dépendances pour vulnérabilités | 0.5223 | 0.7418 | 0.8938 | ✅ |
+| pt | verificar dependências por vulnerabilidades | 0.4381 | 0.7899 | 0.9605 | ✅ |
+| ru | проверить зависимости на уязвимости | 0.0295 | 0.7592 | 0.8536 | ✅ |
+| ja | 依存関係の脆弱性をチェックして | -0.0290 | 0.6861 | 0.9338 | ✅ |
+| ko | 의존성 취약점 검사 | -0.0163 | 0.7179 | 0.8554 | ✅ |
+| zh | 检查依赖项的漏洞 | -0.0266 | 0.5866 | 0.8874 | ✅ |
+| ar | فحص التبعيات بحثاً عن ثغرات | 0.0416 | 0.3995 | 0.9581 | ✅ |
+| el | έλεγχος εξαρτήσεων για ευπάθειες | -0.0118 | 0.5934 | 0.8065 | ✅ |
+| en | write a conventional commit message | 0.7930 | 0.7465 | 0.7465 | ✅ |
+| ja | コミットメッセージを書いて | 0.0929 | 0.5314 | 0.8322 | ✅ |
+| ko | 커밋 메시지 작성 | 0.1070 | 0.4847 | 0.8074 | ✅ |
+| zh | 写一个规范的提交信息 | 0.0727 | 0.6833 | 0.8896 | ✅ |
+| de | eine konventionelle Commit-Nachricht schreiben | 0.3081 | 0.6349 | 0.7801 | ✅ |
+| ru | написать сообщение коммита | 0.0039 | 0.4563 | 0.5000 | ✅ |
+| en | add unit tests for the auth module | 0.5089 | 0.7411 | 0.7411 | ✅ |
+| ja | 認証モジュールのユニットテストを追加して | 0.0009 | 0.7461 | 0.8338 | ✅ |
+| ko | 인증 모듈에 단위 테스트 추가 | 0.0917 | 0.5602 | 0.7660 | ✅ |
+| zh | 为认证模块添加单元测试 | 0.0162 | 0.7100 | 0.8278 | ✅ |
+| de | Unit-Tests für das Auth-Modul hinzufügen | 0.4085 | 0.7445 | 0.8100 | ✅ |
+| ru | добавить юнит-тесты для модуля аутентификации | 0.0629 | 0.1650 | 0.3210 | ✅ |
+
+## Summary
+
+- **Tests:** 23
+- **Passed:** 23
+- **Failed:** 0
+- **Accuracy:** 100.0%
+
+## Timing
+
+| Phase | Duration | Tests | Per-test |
+|:------|:---------|------:|---------:|
+| EN model batch (23 pairs) | 104ms | 23 | 4ms |
+| Multi model cross-language (23 pairs) | 392ms | 23 | 17ms |
+| Multi model same-language (23 pairs) | 389ms | 23 | 16ms |
+| **Total** | **889ms** | **69** | **12ms** |
+
+## Interpretation
+
+The multilingual model enables three matching strategies:
+
+1. **English ways + English model** — current production. High precision for English prompts.
+2. **English ways + multilingual model (cross-language)** — user types in any language, matches against English descriptions. Works but scores 30-50% lower.
+3. **Native-language stubs + multilingual model (same-language)** — frontmatter-only `.ja.md` stubs with native descriptions. Consistently scores 0.80+ across tested languages.
+
+**Recommendation:** Ship both models. English ways use the English model (precise, 21MB). Multilingual stubs use the multilingual model (broad, 127MB). Per-way `embed_model` frontmatter field controls routing. This gives per-language threshold tuning without compromising English accuracy.

docs/architecture/system/multilingual-model-evaluation.md

@@ -0,0 +1,130 @@
+# Multi-Language Support
+
+Ways supports multilingual matching and output across 52 languages. The system uses two embedding models: a precise English model and a broad multilingual model, routed per-way via frontmatter.
+
+## Setting output language
+
+The agent writes commit messages, comments, and documentation in the configured language. Resolution order:
+
+1. **`ways.json`** `output_language` field — explicit override
+2. **Claude Code** `settings.json` `language` field — agent config (project then user)
+3. **System locale** (`$LC_ALL` → `$LC_MESSAGES` → `$LANG`)
+4. **Default**: `en`
+
+```json
+// ways.json — explicit override
+{"disabled": [], "output_language": "ja"}
+```
+
+```json
+// Claude Code settings.json — agent-level
+{"language": "japanese"}
+```
+
+Setting `output_language: "auto"` skips the override and cascades to Claude Code settings → system locale.
+
+The output language directive is injected via `core.md` at session start. Way content (the guidance text) stays English — the agent reads it fine in any language. Only the file output changes.
+
+## How matching works across languages
+
+Two embedding models handle different matching scenarios:
+
+| Model | File | Size | Languages | Use case |
+|-------|------|------|-----------|----------|
+| all-MiniLM-L6-v2 | `minilm-l6-v2.gguf` | 21MB | English | Precise EN matching (default) |
+| paraphrase-multilingual-MiniLM-L12-v2 | `multilingual-minilm-l12-v2-q8.gguf` | 127MB | 52 | Cross-language and same-language matching |
+
+Both are downloaded by `make setup` and stored in `~/.cache/claude-ways/user/`.
+
+Each way declares which model it uses via the `embed_model` frontmatter field:
+
+```yaml
+---
+description: security vulnerability scanning
+vocabulary: security vulnerability CVE audit
+embed_model: en          # default — uses English model
+embed_threshold: 0.35
+---
+```
+
+Ways with `embed_model: multilingual` are scored by the multilingual model against a separate corpus.
+
+## Creating language stubs
+
+A language stub is a frontmatter-only `.{lang}.md` file that provides native-language matching vocabulary for an existing way. The way body stays English — only the matching changes.
+
+```
+hooks/ways/softwaredev/code/security/
+  security.md           # English way — full body + frontmatter
+  security.ja.md        # Japanese stub — frontmatter only, no body
+  security.ko.md        # Korean stub — frontmatter only, no body
+```
+
+Example stub (`security.ja.md`):
+
+```yaml
+---
+description: セキュリティ脆弱性スキャンと監査
+vocabulary: セキュリティ 脆弱性 CVE 監査 認証 暗号化
+embed_model: multilingual
+embed_threshold: 0.25
+---
+```
+
+When a Japanese user types a prompt, the scanner:
+1. Matches `security.ja.md`'s frontmatter using the multilingual model
+2. Injects `security.md`'s English body (the guidance text)
+
+The agent reads the English guidance and responds in the configured output language.
+
+### Why same-language stubs matter
+
+Cross-language matching (Japanese prompt → English description) scores ~0.69. Same-language matching (Japanese prompt → Japanese description) scores ~0.93. The stub's native-language description dramatically improves matching precision.
+
+| Scenario | Cosine similarity |
+|----------|----------------:|
+| EN prompt → EN description (baseline) | 0.76 |
+| JA prompt → EN description (cross-language) | 0.69 |
+| JA prompt → JA description (same-language stub) | 0.93 |
+
+See `docs/architecture/system/multilingual-model-evaluation.md` for full test results.
+
+## Supported languages
+
+Languages are defined in `tools/ways-cli/languages.json`. Each entry specifies:
+
+- **`name`** / **`native`** — display names for normalization
+- **`bm25_stemmer`** — Snowball stemmer algorithm name, or `"impossible"` if BM25 cannot support this language
+
+### BM25 feasibility
+
+BM25 is the fallback matching engine when the embedding model is unavailable. It works for languages with whitespace word boundaries and suffix-stripping morphology:
+
+**BM25 works**: Danish, Dutch, English, Finnish, French, German, Greek, Hungarian, Italian, Norwegian, Portuguese, Romanian, Russian, Spanish, Swedish, Turkish
+
+**BM25 impossible**: Arabic, Burmese, Chinese, Georgian, Gujarati, Hebrew, Hindi, Japanese, Korean, Marathi, Mongolian, Thai, Urdu, Vietnamese — and others marked `"impossible"` in `languages.json`
+
+For "impossible" languages, the embedding engine is required — not optional. Without it, only keyword/regex patterns fire.
+
+## Checking language status
+
+```bash
+# Language coverage report
+ways language
+
+# Filter to a specific language
+ways language --filter ja
+
+# Machine-readable
+ways language --json
+
+# Engine status with corpus breakdown
+ways status
+```
+
+`ways status` warns if multilingual ways exist in the corpus but the multilingual model is missing.
+
+## Architecture decisions
+
+- **ADR-107**: Full design rationale — language cascade, dual model approach, matching tiers
+- **Evaluation report**: `docs/architecture/system/multilingual-model-evaluation.md` — test data across 11 languages × 3 domains

docs/hooks-and-ways/languages.md

@@ -10,6 +10,8 @@ INPUT=$(cat)
 CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
 DESC=$(echo "$INPUT" | jq -r '.tool_input.description // empty' | tr '[:upper:]' '[:lower:]')
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id // empty')
+[[ -n "$AGENT_ID" ]] && export CLAUDE_AGENT_ID="$AGENT_ID"
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(echo "$INPUT" | jq -r '.cwd // empty')}"
 
 export CLAUDE_PROJECT_DIR="${PROJECT_DIR}"

hooks/ways/check-bash-pre.sh

@@ -9,6 +9,8 @@ source "$(dirname "$0")/require-ways.sh"
 INPUT=$(cat)
 FP=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id // empty')
+[[ -n "$AGENT_ID" ]] && export CLAUDE_AGENT_ID="$AGENT_ID"
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(echo "$INPUT" | jq -r '.cwd // empty')}"
 
 [[ -z "$FP" ]] && exit 0

hooks/ways/check-file-pre.sh

@@ -11,6 +11,8 @@ INPUT=$(cat)
 PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' | tr '[:upper:]' '[:lower:]')
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(echo "$INPUT" | jq -r '.cwd // empty')}"
+AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id // empty')
+[[ -n "$AGENT_ID" ]] && export CLAUDE_AGENT_ID="$AGENT_ID"
 
 # Read response topics from Stop hook (if available)
 RESPONSE_STATE="/tmp/claude-response-topics-${SESSION_ID}"

hooks/ways/check-prompt.sh

@@ -9,6 +9,8 @@
 
 INPUT=$(cat)
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id // empty')
+[[ -n "$AGENT_ID" ]] && export CLAUDE_AGENT_ID="$AGENT_ID"
 TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty')
 STOP_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
 

hooks/ways/check-response.sh

@@ -8,6 +8,8 @@ source "$(dirname "$0")/require-ways.sh"
 
 INPUT=$(cat)
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id // empty')
+[[ -n "$AGENT_ID" ]] && export CLAUDE_AGENT_ID="$AGENT_ID"
 TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty')
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(echo "$INPUT" | jq -r '.cwd // empty')}"
 

hooks/ways/check-state.sh

@@ -10,6 +10,8 @@ source "$(dirname "$0")/require-ways.sh"
 INPUT=$(cat)
 TASK_PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // empty' | tr '[:upper:]' '[:lower:]')
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id // empty')
+[[ -n "$AGENT_ID" ]] && export CLAUDE_AGENT_ID="$AGENT_ID"
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(echo "$INPUT" | jq -r '.cwd // empty')}"
 TEAM_NAME=$(echo "$INPUT" | jq -r '.tool_input.team_name // empty')
 

hooks/ways/check-task-pre.sh

@@ -28,6 +28,12 @@ way:
       required: optional
       default: 0.35
       role: Cosine similarity threshold for embedding engine (0.0-1.0, higher = stricter)
+    embed_model:
+      type: enum
+      values: [en, multilingual]
+      required: optional
+      default: en
+      role: Which embedding model to match against (en = all-MiniLM-L6-v2, multilingual = paraphrase-multilingual-MiniLM-L12-v2)
     pattern:
       type: regex
       required: optional