companion-for-agy 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,71 +1,97 @@
 # Changelog
 
+## [Unreleased]
+
+## [1.3.0] - 2026-06-07
+
+### Added
+- CLI localization via `--lang <code>` and locale auto-detection.
+- Supported CLI/documentation languages: English, German, Spanish, Simplified Chinese, Japanese, and Russian.
+- New localization module `src/locales.mjs`.
+- Translated README files: `README_de.md`, `README_es.md`, `README_zh-Hans.md`, `README_ja.md`, `README_ru.md`.
+- German changelog: `CHANGELOG_de.md`.
+- CLI regression tests for localized help and parsing errors.
+
+### Changed
+- User-facing CLI strings are now read from locale maps instead of being hardcoded in `src/agy-companion.mjs`.
+- `package.json` now includes all localized documentation files in the npm package.
+- Documentation now distinguishes CLI output localization, documentation translation, and agy TUI recognition patterns.
+
+### Fixed
+- Empty/non-extractable responses now exit nonzero instead of falling back to startup banner text or reporting success.
+- Shutdown no longer force-kills the PTY when `Ctrl+C` already produced a clean exit, avoiding late `node-pty` cleanup stacktraces in successful runs.
+- `researcher` and `read-only` permission presets now deny `command(*)` to prevent command-based writes.
+- Unknown CLI options now fail fast; `--` can be used before prompts that start with a dash.
+- Response color can now be overridden via `AGY_COMPANION_RESPONSE_RGB`.
+- German trust/startup patterns, signal cleanup, dead-code cleanup, and one-character prompt/answer handling are covered by tests.
+- agy v1.0.x can be used by omitting the model flag via `--no-model` or `AGY_COMPANION_NO_MODEL`.
+
 ## [1.2.0] - 2026-06-07
 
 ### Fixed (Bugsweep)
-- **Security:** Stale temp workspace from crashed run with same PID could leak permissions to new run — now cleaned on startup (`e8c5230`)
-- Temp directory leak in sandbox/skip-permissions modes when no custom rules are set (`d406299`)
-- Temp cleanup race on Windows: post-kill delay + rmSync retries for CWD lock (`41412d6`)
-- ConPTY text extraction: stale cursor position, bold SGR false-positive, dedup scope too narrow (`c2194bb`)
-- isNoiseLine false positives for blockquotes (`>`) and lines containing "tokens" keyword (`f6a8e7b`)
+- **Security:** Stale temp workspace from crashed run with same PID could leak permissions to a new run; it is now cleaned on startup (`e8c5230`).
+- Temp directory leak in sandbox/skip-permissions modes when no custom rules are set (`d406299`).
+- Temp cleanup race on Windows: post-kill delay plus `rmSync` retries for CWD locks (`41412d6`).
+- ConPTY text extraction: stale cursor position, bold SGR false positive, and too-narrow deduplication scope (`c2194bb`).
+- `isNoiseLine` false positives for blockquotes (`>`) and lines containing the word "tokens" (`f6a8e7b`).
 
 ## [1.2.0-alpha.2] - 2026-06-07
 
 ### Changed
-- Brand ASCII banner aligned to left in READMEs
-- Switched image source to raw GitHub URLs to fix logo rendering on npmjs.com
+- Brand ASCII banner aligned to the left in READMEs.
+- Switched image source to raw GitHub URLs to fix logo rendering on npmjs.com.
 
 ### Fixed
-- Handled additional CLI tip noise (lines starting with `└`) and "Verifying..." lines in output parser
+- Handled additional CLI tip noise (lines starting with `└`) and "Verifying..." lines in the output parser.
 
 ## [1.2.0-alpha.1] - 2026-06-07
 
 ### Changed
-- Package renamed to `companion-for-agy` (legal/trademark distancing via "for" pattern)
-- Added "Unofficial" disclaimer to README and package description
+- Package renamed to `companion-for-agy` for legal/trademark distancing via the "for" pattern.
+- Added "Unofficial" disclaimer to README and package description.
 
 ### Fixed
-- Short responses (≤2 chars like "4", "42", "ja") were incorrectly filtered as noise
-- Prompt-echo bug in `--no-tools` mode: the permission prefix ("IMPORTANT: Do not use...") was returned as the response instead of the actual answer
-- ConPTY space-loss in prompt echo: whitespace-normalized matching now handles "Donotuse" vs "Do not use"
+- Short responses (2 or fewer characters like "4", "42", "ja") were incorrectly filtered as noise.
+- Prompt-echo bug in `--no-tools` mode: the permission prefix was returned as the response instead of the actual answer.
+- ConPTY space loss in prompt echo: whitespace-normalized matching now handles "Donotuse" versus "Do not use".
 
 ### Added
-- `stripPromptEcho()` — whitespace-tolerant prompt echo removal (word-by-word regex)
-- `extractResponse()` now accepts 4th parameter `effectiveFilter` for full prompt echo stripping
-- 5-phase state machine: Trust dialog auto-confirmation phase
-- Banner model detection: JSON reports actual model from agy's banner
-- 26 new tests (107 total): short answer extraction, prompt echo regression, stripPromptEcho unit tests
-- `companion-for-agy` CLI alias (alongside `agy-companion` for backward compatibility)
+- `stripPromptEcho()` for whitespace-tolerant prompt echo removal.
+- `extractResponse()` accepts a fourth parameter, `effectiveFilter`, for full prompt echo stripping.
+- 5-phase state machine with a trust dialog auto-confirmation phase.
+- Banner model detection: JSON reports the actual model from agy's banner.
+- 26 new tests (107 total): short-answer extraction, prompt echo regression, and `stripPromptEcho` unit tests.
+- `companion-for-agy` CLI alias alongside `agy-companion` for backward compatibility.
 
 ## [1.1.0] - 2026-06-06
 
 ### Changed
-- Cross-platform support: Windows, macOS, Linux (node-pty handles platform-specific PTY)
-- Auto-detection of agy binary via PATH, common install locations, env var fallback
-- node-pty loaded as standard npm dependency (no hardcoded path to gemini-cli internals)
-- Debug log writes to `./agy-debug.log` (CWD) instead of `~/.claude/scripts/`
-- CLI messages and usage text in English for international audience
-- Added English INIT_DONE_PATTERNS alongside German ones
-- Removed `"os": ["win32"]` restriction from package.json
+- Cross-platform support: Windows, macOS, Linux (`node-pty` handles platform-specific PTYs).
+- Auto-detection of the agy binary via PATH, common install locations, and environment variable fallback.
+- `node-pty` loaded as a standard npm dependency, without a hardcoded path to gemini-cli internals.
+- Debug log writes to `./agy-debug.log` instead of `~/.claude/scripts/`.
+- CLI messages and usage text in English for an international audience.
+- Added English `INIT_DONE_PATTERNS` alongside German ones.
+- Removed the `"os": ["win32"]` restriction from `package.json`.
 
 ### Added
-- `findAgyPath()` exported function for programmatic agy detection
-- Test suite: 81 tests (unit, fixture, smoke) via `node:test`
-- `npm run deploy` and `npm run sync` scripts for local copy management
-- Comprehensive README with installation, troubleshooting, and usage docs
+- Exported `findAgyPath()` for programmatic agy detection.
+- Test suite: 81 tests (unit, fixture, smoke) via `node:test`.
+- `npm run deploy` and `npm run sync` scripts for local copy management.
+- Comprehensive README with installation, troubleshooting, and usage docs.
 
 ## [1.0.0] - 2026-06-06
 
-### Hinzugefügt
-- ConPTY-basierter Wrapper für agy (Antigravity CLI)
-- ANSI-Color-basierte Response-Extraktion (RGB 232,234,237)
-- Fallback: Zeilen-basierte Noise-Filterung
-- 4-Phasen State-Machine (Startup → Init → Question → Response)
-- Adaptives Timing (10s während Generierung, 2.5s nach Abschluss)
-- Permission-System mit 5 Modi: sandbox, skip-permissions, no-tools, researcher, read-only
-- Custom allow/deny Regeln (kompatibel mit agys settings.json-Format)
-- JSON-Output-Modus (--json)
-- Konfigurierbare Pfade via Umgebungsvariablen
-- Prompt-Sanitisierung gegen PTY-Injection
-- Graceful Shutdown (Ctrl+C → Grace-Period → kill)
-- Debug-Modus mit PTY-Output-Log
+### Added
+- ConPTY-based wrapper for agy (Antigravity CLI).
+- ANSI-color-based response extraction (`RGB(232,234,237)`).
+- Line-based noise-filter fallback.
+- 4-phase state machine (startup, init, question, response).
+- Adaptive timing: 10s during generation, 2.5s after completion.
+- Permission system with 5 modes: sandbox, skip-permissions, no-tools, researcher, read-only.
+- Custom allow/deny rules compatible with agy's `settings.json` format.
+- JSON output mode (`--json`).
+- Configurable paths via environment variables.
+- Prompt sanitization against PTY injection.
+- Graceful shutdown.
+- Debug mode with PTY output log.

package/CHANGELOG_de.md

@@ -0,0 +1,97 @@
+# Änderungsprotokoll
+
+## [Unveröffentlicht]
+
+## [1.3.0] - 2026-06-07
+
+### Hinzugefügt
+- CLI-Lokalisierung über `--lang <Code>` und automatische Locale-Erkennung.
+- Unterstützte CLI- und Dokumentationssprachen: Englisch, Deutsch, Spanisch, vereinfachtes Chinesisch, Japanisch und Russisch.
+- Neues Lokalisierungsmodul `src/locales.mjs`.
+- Übersetzte README-Dateien: `README_de.md`, `README_es.md`, `README_zh-Hans.md`, `README_ja.md`, `README_ru.md`.
+- Deutsches Änderungsprotokoll: `CHANGELOG_de.md`.
+- CLI-Regressionstests für lokalisierte Hilfe und lokalisierte Parsing-Fehler.
+
+### Geändert
+- Benutzerseitige CLI-Texte werden nun aus Locale-Maps gelesen und nicht mehr direkt in `src/agy-companion.mjs` hartcodiert.
+- `package.json` liefert alle lokalisierten Dokumentationsdateien im npm-Paket aus.
+- Die Dokumentation trennt nun CLI-Lokalisierung, Dokumentationsübersetzung und agy-TUI-Erkennungsmuster.
+
+### Behoben
+- Leere oder nicht extrahierbare Antworten führen nun zu einem Exit-Code ungleich Null, statt auf Startup-Banner-Text zurückzufallen oder Erfolg zu melden.
+- Das Beenden erzwingt keinen PTY-Kill mehr, wenn `Ctrl+C` bereits zu einem sauberen Exit geführt hat. Das verhindert späte `node-pty`-Bereinigungs-Stacktraces bei erfolgreichen Läufen.
+- Die Berechtigungs-Voreinstellungen `researcher` und `read-only` verbieten nun `command(*)`, um befehlsbasierte Schreibvorgänge zu verhindern.
+- Unbekannte CLI-Optionen schlagen nun sofort fehl; `--` kann vor Prompts genutzt werden, die mit einem Bindestrich beginnen.
+- Die Antwortfarbe kann über `AGY_COMPANION_RESPONSE_RGB` überschrieben werden.
+- Deutsche Trust-/Startup-Muster, Signal-Bereinigung, Bereinigung von totem Code und Ein-Zeichen-Prompt/Antwort-Fälle sind durch Tests abgedeckt.
+- agy v1.0.x kann genutzt werden, indem das Modell-Flag via `--no-model` oder `AGY_COMPANION_NO_MODEL` weggelassen wird.
+
+## [1.2.0] - 2026-06-07
+
+### Behoben (Bug-Sweep)
+- **Sicherheit:** Ein veralteter temporärer Arbeitsbereich eines abgestürzten Laufs mit derselben PID konnte Berechtigungen an einen neuen Lauf übertragen; er wird nun beim Start bereinigt (`e8c5230`).
+- Speicherleck des temporären Verzeichnisses im Sandbox- und Skip-Permissions-Modus, wenn keine benutzerdefinierten Regeln gesetzt sind (`d406299`).
+- Race Condition bei der temporären Bereinigung unter Windows: Post-Kill-Verzögerung plus `rmSync`-Wiederholungen für CWD-Locks (`41412d6`).
+- ConPTY-Textextraktion: veraltete Cursorposition, falsche Erkennung von fettem SGR und zu enger Entduplizierungsbereich (`c2194bb`).
+- False Positives in `isNoiseLine` für Blockzitate (`>`) und Zeilen mit dem Wort "tokens" (`f6a8e7b`).
+
+## [1.2.0-alpha.2] - 2026-06-07
+
+### Geändert
+- ASCII-Banner in den README-Dateien linksbündig ausgerichtet.
+- Bildquelle auf rohe GitHub-URLs umgestellt, damit das Logo auf npmjs.com korrekt gerendert wird.
+
+### Behoben
+- Zusätzliches CLI-Tipp-Rauschen (Zeilen mit `└`) und "Verifying..."-Zeilen im Ausgabe-Parser behandelt.
+
+## [1.2.0-alpha.1] - 2026-06-07
+
+### Geändert
+- Paket in `companion-for-agy` umbenannt, um über das "for"-Muster rechtliche und markenbezogene Distanz zu schaffen.
+- Hinweis "Inoffiziell" in README und Paketbeschreibung ergänzt.
+
+### Behoben
+- Kurze Antworten (2 Zeichen oder weniger, z.B. "4", "42", "ja") wurden fälschlich als Rauschen gefiltert.
+- Prompt-Echo-Bug im Modus `--no-tools`: Das Berechtigungspräfix wurde als Antwort zurückgegeben statt der eigentlichen Antwort.
+- ConPTY-Leerzeichenverlust beim Prompt-Echo: Whitespace-normalisierter Abgleich verarbeitet nun "Donotuse" gegenüber "Do not use".
+
+### Hinzugefügt
+- `stripPromptEcho()` für whitespace-tolerante Entfernung des Prompt-Echos.
+- `extractResponse()` akzeptiert den vierten Parameter `effectiveFilter` für vollständiges Prompt-Echo-Stripping.
+- 5-Phasen-State-Machine mit automatischer Bestätigung des Trust-Dialogs.
+- Banner-Modellerkennung: JSON meldet das tatsächlich erkannte Modell aus agys Banner.
+- 26 neue Tests (insgesamt 107): Extraktion kurzer Antworten, Prompt-Echo-Regression und Unit-Tests für `stripPromptEcho`.
+- CLI-Alias `companion-for-agy` neben `agy-companion` für Abwärtskompatibilität.
+
+## [1.1.0] - 2026-06-06
+
+### Geändert
+- Plattformübergreifende Unterstützung: Windows, macOS, Linux (`node-pty` verarbeitet plattformspezifische PTYs).
+- Automatische Erkennung der agy-Binärdatei über PATH, übliche Installationsorte und Umgebungsvariablen.
+- `node-pty` wird als normale npm-Abhängigkeit geladen, ohne hartcodierten Pfad zu gemini-cli-Interna.
+- Debug-Log schreibt nach `./agy-debug.log` statt nach `~/.claude/scripts/`.
+- CLI-Nachrichten und Nutzungstexte auf Englisch für ein internationales Publikum.
+- Englische `INIT_DONE_PATTERNS` neben deutschen Patterns ergänzt.
+- Einschränkung `"os": ["win32"]` aus `package.json` entfernt.
+
+### Hinzugefügt
+- Exportierte Funktion `findAgyPath()` für programmatische agy-Erkennung.
+- Testsuite: 81 Tests (Unit, Fixture, Smoke) via `node:test`.
+- Skripte `npm run deploy` und `npm run sync` für lokale Kopieverwaltung.
+- Umfassende README mit Installation, Fehlerbehebung und Nutzung.
+
+## [1.0.0] - 2026-06-06
+
+### Hinzugefügt
+- ConPTY-basierter Wrapper für agy (Antigravity CLI).
+- ANSI-farbbasierte Antwortextraktion (`RGB(232,234,237)`).
+- Zeilenbasierter Noise-Filter-Fallback.
+- 4-Phasen-State-Machine (Startup, Init, Frage, Antwort).
+- Adaptives Timing: 10s während Generierung, 2.5s nach Abschluss.
+- Berechtigungssystem mit 5 Modi: sandbox, skip-permissions, no-tools, researcher, read-only.
+- Benutzerdefinierte Allow-/Deny-Regeln, kompatibel mit agys `settings.json`-Format.
+- JSON-Ausgabemodus (`--json`).
+- Konfigurierbare Pfade über Umgebungsvariablen.
+- Prompt-Sanitisierung gegen PTY-Injection.
+- Graceful Shutdown.
+- Debug-Modus mit PTY-Output-Log.

package/README.md

@@ -6,29 +6,35 @@
 
 [![npm](https://img.shields.io/npm/v/companion-for-agy)](https://www.npmjs.com/package/companion-for-agy)
 [![CI](https://github.com/dev-bricks/companion-for-agy/actions/workflows/tests.yml/badge.svg)](https://github.com/dev-bricks/companion-for-agy/actions/workflows/tests.yml)
+[![English](https://img.shields.io/badge/lang-English-blue)](README.md)
 [![Deutsch](https://img.shields.io/badge/lang-Deutsch-blue)](README_de.md)
+[![Español](https://img.shields.io/badge/lang-Espa%C3%B1ol-blue)](README_es.md)
+[![简体中文](https://img.shields.io/badge/lang-%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87-blue)](README_zh-Hans.md)
+[![日本語](https://img.shields.io/badge/lang-%E6%97%A5%E6%9C%AC%E8%AA%9E-blue)](README_ja.md)
+[![Русский](https://img.shields.io/badge/lang-%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9-blue)](README_ru.md)
 
-> **Unofficial** — not affiliated with or endorsed by Google.
+> **Unofficial** - not affiliated with or endorsed by Google.
 
 PTY-based wrapper for **agy** (Antigravity CLI / Gemini CLI) that captures Gemini responses from subprocesses.
 
 ## Problem
 
-`agy -p` (print mode) returns exit 0 but writes no output to stdout — the TUI text-drip renderer (`text_drip.go`) writes to the terminal buffer instead. This is a known bug:
+`agy -p` (print mode) exits with code 0 but writes no response to stdout. Instead, the TUI text-drip renderer (`text_drip.go`) writes to the terminal buffer. Known upstream issues:
 
 - [antigravity-cli#76](https://github.com/google-antigravity/antigravity-cli/issues/76)
 - [gemini-cli#27466](https://github.com/google-gemini/gemini-cli/issues/27466)
 - [antigravity-cli#115](https://github.com/google-antigravity/antigravity-cli/issues/115)
 
-This means no other agent (Claude Code, Codex, CI/CD) can programmatically read agy's responses.
+That means other agents such as Claude Code, Codex, or CI/CD scripts cannot programmatically read agy's responses.
 
 ## Solution
 
-`companion-for-agy` spawns agy inside a virtual terminal via `node-pty` (ConPTY on Windows, forkpty on macOS/Linux) and extracts the response from the ANSI color stream. agy's response text uses `RGB(232,234,237)` — the wrapper tracks ANSI color state and collects only text in that color.
+`companion-for-agy` starts agy inside a virtual terminal via `node-pty` (ConPTY on Windows, forkpty on macOS/Linux) and extracts the response from the ANSI color stream. agy's response text currently uses `RGB(232,234,237)`, so the wrapper tracks ANSI color state and collects only text in that color.
 
-> **Platform note:** The ANSI color extraction (`RGB(232,234,237)`) and the `--model` flag have been verified on **Windows** with agy >= 1.1. macOS and Linux are expected to work via `node-pty` since agy uses the same Go TUI renderer. However:
-> - **agy v1.0.x** (Homebrew `antigravity-cli`) does not support `--model` — the tool will fail with "flags provided but not defined". Update agy or omit `--model` (requires code change).
-> - The exact RGB response color has not been independently confirmed on non-Windows platforms. If color extraction returns empty results, try `--debug` and check `agy-debug.log` for the actual color codes.
+> **Platform note:** ANSI color extraction (`RGB(232,234,237)`) and the `--model` flag have been verified on **Windows** with agy >= 1.1. macOS and Linux are expected to work through `node-pty`, but the exact response color still needs independent verification there.
+>
+> - **agy v1.0.x** (Homebrew `antigravity-cli`) does not support `--model`; use `--no-model` or `AGY_COMPANION_NO_MODEL=1`.
+> - If color extraction returns an empty result, run with `--debug` and inspect `agy-debug.log`.
 
 ## Installation
 
@@ -40,21 +46,15 @@ npm install -g companion-for-agy
 
 - **Node.js >= 18**
 - **agy** ([Gemini CLI](https://github.com/google-gemini/gemini-cli)) installed and authenticated
-- **C/C++ build tools** for `node-pty` native compilation:
-  - **Windows:** [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) + Python 3
+- **C/C++ build tools** for native `node-pty` compilation:
+  - **Windows:** Visual Studio Build Tools + Python 3
   - **macOS:** `xcode-select --install`
   - **Linux:** `sudo apt install build-essential python3` (Debian/Ubuntu)
 
-### Troubleshooting `node-pty` build errors
-
-If `npm install` fails with native compilation errors:
+If native compilation fails, run:
 
 ```bash
-# All platforms: rebuild native modules
 npm rebuild node-pty
-
-# Windows: if cl.exe is not found, install Visual Studio Build Tools
-# then open "Developer Command Prompt" or run from "x64 Native Tools"
 ```
 
 ## Usage
@@ -67,17 +67,17 @@ companion-for-agy [options] "prompt"
 
 | Flag | Description |
 |------|-------------|
-| `--sandbox` | Sandbox mode (default) — tools in container |
+| `--sandbox` | Sandbox mode (default), tools in container |
 | `--skip-permissions` | All tools without confirmation (YOLO) |
-| `--no-tools` | Pure chat — no tool execution |
-| `--researcher` | Web search allowed, no file changes |
-| `--read-only` | Read-only, no modifications |
+| `--no-tools` | Pure chat, no tool execution |
+| `--researcher` | Web/search research allowed, shell commands and file changes denied |
+| `--read-only` | File reads allowed, shell commands and modifications denied |
 
 ### Custom Rules
 
 ```bash
 --allow "read_file(/path)"    # Allowlist rule (repeatable)
---deny "command(rm)"           # Denylist rule (repeatable)
+--deny "command(rm)"          # Denylist rule (repeatable)
 ```
 
 Formats match agy's own permission system (`settings.json`).
@@ -87,72 +87,88 @@ Formats match agy's own permission system (`settings.json`).
 | Flag | Description |
 |------|-------------|
 | `--model <model>` | Gemini model (default: `gemini-3.5-flash`) |
-| `--timeout <ms>` | Timeout in ms (default: 120000) |
+| `--no-model` | Do not pass `--model` to agy; useful for agy v1.0.x |
+| `--timeout <ms>` | Timeout in ms (default: `120000`) |
 | `--json` | Output as JSON object |
 | `--debug` | Save raw PTY output to `agy-debug.log` |
+| `--lang <code>` | CLI output language: `en`, `de`, `es`, `zh-Hans`, `ja`, `ru` |
+| `--` | Stop option parsing; use before prompts that start with `-` |
 
 ### Environment Variables
 
 | Variable | Description |
 |----------|-------------|
-| `AGY_COMPANION_AGY_PATH` | Path to agy binary (auto-detected if not set) |
+| `AGY_COMPANION_AGY_PATH` | Path to agy binary (auto-detected if unset) |
 | `AGY_PATH` | Alternative path to agy binary |
+| `AGY_COMPANION_NO_MODEL` | Set to `1`, `true`, or `yes` to omit `--model` |
+| `AGY_COMPANION_RESPONSE_RGB` | Override response color as `R,G,B` or `R;G;B` |
 
 ### Examples
 
 ```bash
-# Simple question
 companion-for-agy "What is the capital of Bavaria?"
-
-# As advisor (no tool use)
 companion-for-agy --no-tools "Review this code: ..."
-
-# Web research
 companion-for-agy --researcher "Latest info on Node.js 24"
-
-# Read-only with additional git permission
 companion-for-agy --read-only --allow "command(git log)" "prompt"
-
-# JSON output for programmatic use
 companion-for-agy --json --model gemini-3.5-pro "prompt"
-# → {"response":"...","model":"Gemini 3.5 Pro (High)","requestedModel":"gemini-3.5-pro","permissionMode":"sandbox"}
+companion-for-agy --no-model "prompt"
+companion-for-agy --lang de --help
+companion-for-agy --no-tools -- "-dash-prefixed prompt"
 ```
 
-> **JSON fields:** `model` reports the actual model detected from agy's banner (e.g., `"Gemini 3.5 Flash (Medium)"`). `requestedModel` is what was passed via `--model`. If banner detection fails, `model` falls back to `requestedModel`.
+JSON output includes `response`, `model`, `requestedModel`, and `permissionMode`. `model` is detected from agy's banner when possible and falls back to `requestedModel`.
+
+## Internationalization Scope
+
+There are three separate i18n surfaces:
+
+1. **companion-for-agy CLI output:** help text, errors, and status lines produced by this wrapper.
+2. **Documentation:** README, contributing guide, changelog, and examples.
+3. **agy TUI recognition patterns:** internal regexes that detect agy's trust dialog, startup readiness, init completion, and response completion.
+
+Local Windows checks showed that `agy --help` stayed English under `LANG=en_US`, `de_DE`, `ja_JP`, and `zh_CN`. That suggests agy's CLI help is currently English-only, but it does not prove every TUI dialog, future agy release, plugin, or OS-specific flow will stay English.
+
+Planned user-facing languages:
+
+| Code | Language | Scope |
+|------|----------|-------|
+| `en` | English | Default CLI and canonical docs |
+| `de` | German | Translated docs and CLI output |
+| `es` | Spanish | Translated docs and CLI output |
+| `zh-Hans` | Simplified Chinese | Translated docs and CLI output |
+| `ja` | Japanese | Translated docs and CLI output |
+| `ru` | Russian | Translated docs and CLI output |
+
+Recognition patterns are not blindly translated. English stays the baseline; non-English patterns are added only when agy actually emits those strings or a stable upstream string is documented.
 
 ## How It Works
 
-```
-┌────────────────────┐       PTY       ┌─────────────┐
-│ companion-for-agy  │ ─────────────▸  │     agy     │
-│     (Node.js)      │ ◂────────────── │  (Go TUI)   │
-│                    │  ANSI stream    │             │
-│  Color-Based       │                 │ text_drip.go│
-│  Extraction        │                 │ RGB(232,234,│
-│                    │                 │     237)    │
-└────────┬───────────┘                 └─────────────┘
-         │
-         ▼ stdout
-     Response text
+```text
+companion-for-agy (Node.js)
+  -> starts agy in a PTY
+  -> detects trust/startup/init states
+  -> sends the prompt
+  -> captures ANSI response-color segments
+  -> writes response text to stdout
 ```
 
-**5-Phase State Machine:**
+**5-phase state machine:**
 
-1. **Trust** — detect and auto-confirm workspace trust dialog
-2. **Startup** — detect main UI readiness (`? for shortcuts`)
-3. **Init** — wait for GEMINI.md initialization (pattern matching or 20s fallback)
-4. **Question** — send prompt, set response marker
-5. **Response** — read response via ANSI color extraction, adaptive idle timer
+1. **Trust:** detect and auto-confirm workspace trust dialog
+2. **Startup:** detect main UI readiness (`? for shortcuts`)
+3. **Init:** wait for initialization, with timeout fallback
+4. **Question:** send prompt and mark response start
+5. **Response:** extract response via ANSI color and adaptive idle timers
 
 ## Use Cases
 
-- **Multi-agent orchestration**: Claude Code, Codex, or other agents querying Gemini via agy
-- **CI/CD pipelines**: automated Gemini queries in build scripts
-- **Scripting**: any scenario where agy's response needs to be captured as text
+- Multi-agent orchestration: Claude Code, Codex, or other agents querying Gemini via agy
+- CI/CD scripts that need text output from agy
+- Local automation where agy's TUI response must be captured as stdout
 
 ## Background
 
-This tool was built because three CLI agents — **Claude Code**, **Codex**, and **agy** — need to call each other as fallback advisors. While Claude → Codex and agy → Claude/Codex already work, Claude → agy was blocked by the TUI stdout bug.
+This tool was built because three CLI agents - Claude Code, Codex, and agy - need to call each other as fallback advisors. Claude to Codex and agy to Claude/Codex already worked; Claude to agy was blocked by the TUI stdout bug.
 
 ## License