ollama-intern-mcp 2.2.0 → 2.3.0

package/README.es.md

@@ -29,6 +29,46 @@ Sin nube. Sin telemetría. Nada de "autonomía". Cada llamada muestra su trabajo
 
 ## Novedades en v2.2.0
 
+Modelo configurable por llamada para las herramientas atomizadas basadas en LLM. Pequeñas mejoras adicionales; los usuarios de la versión v2.2.0 no se ven afectados. Detalles en [CHANGELOG.md](./CHANGELOG.md) y [docs/release-notes/v2.3.0.md](./docs/release-notes/v2.3.0.md).
+
+- **Entrada opcional `model: string` en 8 herramientas atomizadas** — `ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep`, `ollama_research`, `ollama_corpus_answer`, `ollama_chat`, `ollama_code_citation`. El primer intento en el nivel de la herramienta utiliza el modelo especificado por el usuario; en caso de tiempo de espera, la cascada existente `TIER_FALLBACK` utiliza el modelo propio del nivel más económico (NO la configuración del usuario). Las herramientas compuestas/resumidas/de paquete *deliberadamente* no aceptan el parámetro `model`; las herramientas atomizadas tienen control por llamada, mientras que las herramientas compuestas utilizan los valores predeterminados del nivel.
+- **Nuevo campo de la estructura `model_requested?: string`** — presente solo cuando se proporciona la configuración. Los usuarios que realizan la calibración comparan `model_requested` con `model` para detectar la sustitución: `if (env.model_requested && env.model !== env.model_requested) { /* sustitución */ }`. Las entradas vacías o que contienen solo espacios en blanco generan un error `ZodError` durante el análisis del esquema, en lugar de una sustitución silenciosa.
+- **Corrección de errores — desviación en `src/version.ts`.** La constante de tiempo de ejecución `VERSION` ahora se lee del archivo `package.json` al cargar el módulo; las versiones v2.1.0 y v2.2.0 se enviaron con la cadena de identificación obsoleta `"2.0.0"`. La nueva prueba `tests/version.test.ts` verifica que `VERSION === pkg.version`.
+
+### Configuración de modelo por llamada (nueva en la versión v2.3.0)
+
+```jsonc
+{
+  "tool": "ollama_classify",
+  "arguments": {
+    "text": "patch null pointer in auth",
+    "labels": ["feat", "fix", "chore"],
+    "frame": "what is the change kind?",
+    "model": "hermes3:8b"
+  }
+}
+```
+
+Estructura:
+
+```jsonc
+{
+  "result": { "label": "fix", "confidence": 0.9, "off_topic": false, ... },
+  "tier_used": "instant",
+  "model": "hermes3:8b",
+  "model_requested": "hermes3:8b",       // present because override was supplied
+  // ... rest of envelope unchanged
+}
+```
+
+Si el nivel "workhorse/deep" hubiera alcanzado el tiempo de espera y la llamada se hubiera redirigido al nivel "instant", `env.model` sería el modelo utilizado por el nivel "instant" y `env.fallback_from` sería `"workhorse"`; `env.model_requested` seguiría siendo `"hermes3:8b"`, y `env.model !== env.model_requested` indica la sustitución. La configuración *deliberadamente* no se propaga al nivel más económico; el modelo elegido podría no ser adecuado para el rol de ese nivel.
+
+### Histórico — entregables de v2.1.0
+
+Consulte [CHANGELOG.md](./CHANGELOG.md) y [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md) para ver la entrada completa de la versión v2.2.0 (relevancia temática y abstención estructurada).
+
+## Novedades en v2.2.0
+
 Contrato de rol de agente local de procesamiento de evidencia: relevancia temática y abstención estructurada. Pequeña adición — las llamadas de la versión v2.1.0 no han cambiado. Consulta las entradas detalladas en [CHANGELOG.md](./CHANGELOG.md) y [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md).
 
 - **Extracción basada en el contexto** en `ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep` — entrada opcional `frame: string` + salidas estructuradas `frame_alignment` / `on_topic` / `frame_addressed`. Las fuentes que no son relevantes se marcan en lugar de parafrasearse en el esquema.

package/README.fr.md

@@ -29,6 +29,46 @@ Pas de cloud. Pas de télémétrie. Rien d' "autonome". Chaque appel montre son
 
 ## Nouveau dans la version 2.2.0
 
+Modification du modèle par appel pour les outils atomiques basés sur les LLM. Amélioration mineure additive — les appelants de la version v2.2.0 restent inchangés. Détails dans [CHANGELOG.md](./CHANGELOG.md) et [docs/release-notes/v2.3.0.md](./docs/release-notes/v2.3.0.md).
+
+- **Entrée optionnelle `model: string` pour 8 outils atomiques** — `ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep`, `ollama_research`, `ollama_corpus_answer`, `ollama_chat`, `ollama_code_citation`. La première tentative sur le niveau de l'outil utilise le modèle spécifié par l'appelant ; en cas de dépassement de délai, la cascade `TIER_FALLBACK` existante utilise le modèle du niveau le moins coûteux (et non le modèle spécifié par l'appelant). Les outils composites/résumés/groupés n'acceptent *délibérément* pas l'argument `model` ; les atomes permettent un contrôle par appel, tandis que les composites utilisent les paramètres par défaut du niveau.
+- **Nouveau champ de l'enveloppe `model_requested?: string`** — présent uniquement lorsque le modèle a été spécifié. Les appelants sensibles à la calibration comparent `model_requested` à `model` pour détecter le remplacement par défaut : `if (env.model_requested && env.model !== env.model_requested) { /* remplacement */ }`. Les entrées vides ou contenant uniquement des espaces déclenchent une erreur `ZodError` lors de l'analyse du schéma, et non un comportement silencieux.
+- **Correction de bug — dérive dans `src/version.ts`.** La constante `VERSION` est maintenant lue à partir de `package.json` lors du chargement du module ; les versions v2.1.0 et v2.2.0 contenaient une chaîne d'identification obsolète `"2.0.0"`. Un nouveau fichier `tests/version.test.ts` vérifie que `VERSION === pkg.version`.
+
+### Modification du modèle par appel (nouvelle fonctionnalité dans la version v2.3.0)
+
+```jsonc
+{
+  "tool": "ollama_classify",
+  "arguments": {
+    "text": "patch null pointer in auth",
+    "labels": ["feat", "fix", "chore"],
+    "frame": "what is the change kind?",
+    "model": "hermes3:8b"
+  }
+}
+```
+
+Enveloppe :
+
+```jsonc
+{
+  "result": { "label": "fix", "confidence": 0.9, "off_topic": false, ... },
+  "tier_used": "instant",
+  "model": "hermes3:8b",
+  "model_requested": "hermes3:8b",       // present because override was supplied
+  // ... rest of envelope unchanged
+}
+```
+
+Si le niveau "workhorse/deep" a expiré et que l'appel a été redirigé vers le niveau "instant", `env.model` serait le modèle utilisé par le niveau "instant" et `env.fallback_from` serait `"workhorse"` — `env.model_requested` serait toujours `"hermes3:8b"`, et `env.model !== env.model_requested` indique le remplacement. Le modèle spécifié par l'appelant n'est *délibérément* pas transmis au niveau le moins coûteux ; le modèle choisi peut ne pas correspondre à la fonction de ce niveau.
+
+### Historique — livrables de la version 2.1.0
+
+Consultez [CHANGELOG.md](./CHANGELOG.md) et [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md) pour l'intégralité de l'entrée de la version v2.2.0 (pertinence contextuelle et abstention structurée).
+
+## Nouveau dans la version 2.2.0
+
 Contrat du rôle d'agent de collecte de preuves local : pertinence thématique et abstention structurée. Amélioration mineure — les appels de la version 2.1.0 restent inchangés. Détails dans [CHANGELOG.md](./CHANGELOG.md) et [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md).
 
 - **Extraction contextuelle** sur `ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep` — entrée optionnelle `frame: string` + sorties structurées `frame_alignment` / `on_topic` / `frame_addressed`. Les sources hors sujet sont signalées au lieu d'être paraphrasées dans le schéma.

package/README.hi.md

@@ -29,6 +29,46 @@
 
 ## v2.2.0 में नया
 
+प्रत्येक कॉल के लिए मॉडल को बदलने की सुविधा, जो LLM-आधारित एटम टूल में उपलब्ध है। मामूली बदलाव किए गए हैं, v2.2.0 में कॉल करने वालों में कोई बदलाव नहीं हुआ। विस्तृत जानकारी [CHANGELOG.md](./CHANGELOG.md) और [docs/release-notes/v2.3.0.md](./docs/release-notes/v2.3.0.md) में उपलब्ध है।
+
+- **8 एटम टूल में वैकल्पिक `model: string` इनपुट:** `ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep`, `ollama_research`, `ollama_corpus_answer`, `ollama_chat`, `ollama_code_citation`. टूल के पहले प्रयास में, कॉल करने वाले द्वारा निर्दिष्ट मॉडल का उपयोग किया जाता है; यदि समय समाप्त हो जाता है, तो मौजूदा `TIER_FALLBACK` प्रणाली, कम खर्चीले स्तर के अपने मॉडल का उपयोग करती है (कॉल करने वाले द्वारा किए गए बदलाव का नहीं)। कंपोजिट/संक्षिप्त/पैकेज टूल जानबूझकर `model` को स्वीकार नहीं करते हैं - एटम में प्रति-कॉल नियंत्रण होता है, जबकि कंपोजिट डिफ़ॉल्ट स्तर का उपयोग करते हैं।
+- **नया एनवेलप फ़ील्ड `model_requested?: string`:** यह केवल तभी मौजूद होता है जब मॉडल को बदला गया हो। कैलिब्रेशन-सक्षम कॉल करने वाले `model_requested` की तुलना `model` से करते हैं ताकि यह पता चल सके कि क्या कोई बदलाव किया गया है: `if (env.model_requested && env.model !== env.model_requested) { /* बदलाव */ }`. खाली या केवल रिक्त स्थान वाले इनपुट `ZodError` उत्पन्न करते हैं, स्कीमा पार्सिंग के दौरान, और यह चुपचाप नहीं होता है।
+- **बग ठीक किया गया — `src/version.ts` में त्रुटि।** रनटाइम `VERSION` स्थिरांक अब मॉड्यूल लोड होने पर `package.json` से पढ़ा जाता है; v2.1.0 और v2.2.0 में पुरानी `"2.0.0"` पहचान स्ट्रिंग रिपोर्ट की गई थी। नया `tests/version.test.ts` `VERSION === pkg.version` को सुनिश्चित करता है।
+
+### प्रत्येक कॉल के लिए मॉडल को बदलने की सुविधा (v2.3.0 में नई)।
+
+```jsonc
+{
+  "tool": "ollama_classify",
+  "arguments": {
+    "text": "patch null pointer in auth",
+    "labels": ["feat", "fix", "chore"],
+    "frame": "what is the change kind?",
+    "model": "hermes3:8b"
+  }
+}
+```
+
+एनवेलप:
+
+```jsonc
+{
+  "result": { "label": "fix", "confidence": 0.9, "off_topic": false, ... },
+  "tier_used": "instant",
+  "model": "hermes3:8b",
+  "model_requested": "hermes3:8b",       // present because override was supplied
+  // ... rest of envelope unchanged
+}
+```
+
+यदि 'वर्कहॉर्स/डीप' स्तर में समय समाप्त हो गया था और कॉल 'इंस्टेंट' स्तर पर चला गया था, तो `env.model` 'इंस्टेंट' स्तर के चुने हुए मॉडल को दर्शाता है, और `env.fallback_from` `"workhorse"` होगा - `env.model_requested` अभी भी `"hermes3:8b"` होगा, और `env.model !== env.model_requested` बदलाव का संकेत है। जानबूझकर, मॉडल को कम खर्चीले स्तर में नहीं ले जाया जाता है; चुना गया मॉडल उस स्तर की भूमिका के लिए उपयुक्त नहीं हो सकता है।
+
+### ऐतिहासिक - v2.1.0 डिलीवरी
+
+v2.2.0 के पूर्ण विवरण (विषय-आधारित और संरचित अस्वीकृति) के लिए [CHANGELOG.md](./CHANGELOG.md) और [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md) देखें।
+
+## v2.2.0 में नया
+
 स्थानीय प्रमाण-कार्यकर्ता भूमिका अनुबंध: फ्रेम-बाउंड प्रासंगिकता और संरचित अस्वीकृति। मामूली अतिरिक्त - v2.1.0 कॉलर्स अपरिवर्तित। [CHANGELOG.md](./CHANGELOG.md) और [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md) में विस्तृत प्रविष्टियाँ।
 
 - `ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep` पर **फ्रेम-बाउंड निष्कर्षण** - वैकल्पिक `frame: string` इनपुट + संरचित `frame_alignment` / `on_topic` / `frame_addressed` आउटपुट। अप्रासंगिक स्रोतों को स्कीमा में पुन: वाक्यांश करने के बजाय चिह्नित किया जाता है।

package/README.it.md

@@ -29,6 +29,46 @@ Nessun cloud. Nessuna telemetria. Niente di "autonomo". Ogni chiamata mostra il
 
 ## Novità nella versione 2.2.0
 
+Override del modello a livello di chiamata per gli strumenti atomici basati su LLM. Modifiche minori additive — i chiamanti di v2.2.0 rimangono invariati. Dettagli nelle sezioni [CHANGELOG.md](./CHANGELOG.md) e [docs/release-notes/v2.3.0.md](./docs/release-notes/v2.3.0.md).
+
+- **Input opzionale `model: string` per 8 strumenti atomici** — `ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep`, `ollama_research`, `ollama_corpus_answer`, `ollama_chat`, `ollama_code_citation`. Il primo tentativo di esecuzione dello strumento utilizza il modello specificato dal chiamante; in caso di timeout, la cascata `TIER_FALLBACK` esistente risolve il modello del livello più economico (NON l'override specificato dal chiamante). Gli strumenti compositi/sintetici/pacchetti NON accettano deliberatamente il parametro `model` — gli atomi hanno il controllo a livello di chiamata, mentre i compositi utilizzano le impostazioni predefinite del livello.
+- **Nuovo campo dell'inviluppo `model_requested?: string`** — presente solo quando è stato fornito un override. I chiamanti che tengono conto della calibrazione confrontano `model_requested` con `model` per rilevare la sostituzione: `if (env.model_requested && env.model !== env.model_requested) { /* sostituzione */ }`. Gli input vuoti o contenenti solo spazi generano un errore `ZodError` durante l'analisi dello schema, anziché una sostituzione silenziosa.
+- **Correzione di bug — deriva in `src/version.ts`.** La costante `VERSION` a runtime viene ora letta da `package.json` al caricamento del modulo; le versioni v2.1.0 e v2.2.0 sono state distribuite con la stringa di identificazione obsoleta `"2.0.0"`. Il nuovo file `tests/version.test.ts` verifica che `VERSION === pkg.version`.
+
+### Override del modello a livello di chiamata (nuovo in v2.3.0)
+
+```jsonc
+{
+  "tool": "ollama_classify",
+  "arguments": {
+    "text": "patch null pointer in auth",
+    "labels": ["feat", "fix", "chore"],
+    "frame": "what is the change kind?",
+    "model": "hermes3:8b"
+  }
+}
+```
+
+Invio:
+
+```jsonc
+{
+  "result": { "label": "fix", "confidence": 0.9, "off_topic": false, ... },
+  "tier_used": "instant",
+  "model": "hermes3:8b",
+  "model_requested": "hermes3:8b",       // present because override was supplied
+  // ... rest of envelope unchanged
+}
+```
+
+Se il livello "workhorse/deep" avesse superato il tempo limite e la chiamata fosse passata al livello "instant", `env.model` sarebbe il modello risolto dal livello "instant" e `env.fallback_from` sarebbe `"workhorse"` — `env.model_requested` sarebbe ancora `"hermes3:8b"`, e `env.model !== env.model_requested` indica la sostituzione. L'override NON viene deliberatamente propagato al livello più economico; il modello scelto potrebbe non essere adatto al ruolo di quel livello.
+
+### Storico — funzionalità della versione 2.1.0
+
+Consultare [CHANGELOG.md](./CHANGELOG.md) e [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md) per l'elenco completo delle modifiche di v2.2.0 (pertinenza contestuale + astensione strutturata).
+
+## Novità nella versione 2.2.0
+
 Contratto del ruolo di "lavoratore" di evidenze: pertinenza contestuale e astensione strutturata. Modifiche minori additive — le chiamate nella versione 2.1.0 rimangono invariate. Dettagli nelle sezioni [CHANGELOG.md](./CHANGELOG.md) e [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md).
 
 - **Estrazione contestuale** su `ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep` — input opzionale `frame: string` e output strutturati `frame_alignment` / `on_topic` / `frame_addressed`. Le fonti non pertinenti vengono contrassegnate invece di essere riformulate nello schema.

package/README.ja.md

@@ -29,6 +29,46 @@ Claude Codeに、ルール、階層、デスク、そして書類整理棚を備
 
 ## v2.2.0で追加
 
+LLMを活用したツールにおいて、1回の呼び出しごとにモデルを指定できる機能を追加しました。マイナーバージョンアップであり、v2.2.0からの変更点は最小限です。詳細については、[CHANGELOG.md](./CHANGELOG.md) および [docs/release-notes/v2.3.0.md](./docs/release-notes/v2.3.0.md) をご確認ください。
+
+- **8つのツールで、オプションの `model: string` 入力パラメータを追加**：`ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep`, `ollama_research`, `ollama_corpus_answer`, `ollama_chat`, `ollama_code_citation`。ツールの初回実行時に、呼び出し元で指定されたモデルが使用されます。タイムアウトが発生した場合、既存の `TIER_FALLBACK` メカニズムによって、より低コストなティアのデフォルトモデルが選択されます（呼び出し元で指定されたモデルのオーバーライドは適用されません）。複合ツールや簡易ツールは、意図的に `model` パラメータを受け付けません。アトムツールは1回の呼び出しごとにモデルを制御できますが、複合ツールはティアのデフォルト設定を使用します。
+- **新しいフィールド `model_requested?: string` を追加**：オーバーライドが指定された場合にのみ表示されます。呼び出し元は、`model_requested` と `model` を比較することで、フォールバックが発生したかどうかを検出できます。`if (env.model_requested && env.model !== env.model_requested) { /* 置換が発生 */ }`。空の値または空白のみの値が入力された場合、スキーマの解析時に `ZodError` が発生し、黙ってデフォルト値に置き換えられることはありません。
+- **バグ修正：`src/version.ts` の値のずれ**。ランタイムの `VERSION` 定数は、モジュール読み込み時に `package.json` から読み込まれるようになりました。v2.1.0 および v2.2.0 では、古い `"2.0.0"` という文字列が誤ってレポートされていました。新しい `tests/version.test.ts` ファイルで、`VERSION === pkg.version` が検証されるようになりました。
+
+### v2.3.0で新しく追加された、1回の呼び出しごとのモデルのオーバーライド機能
+
+```jsonc
+{
+  "tool": "ollama_classify",
+  "arguments": {
+    "text": "patch null pointer in auth",
+    "labels": ["feat", "fix", "chore"],
+    "frame": "what is the change kind?",
+    "model": "hermes3:8b"
+  }
+}
+```
+
+Envelope:
+
+```jsonc
+{
+  "result": { "label": "fix", "confidence": 0.9, "off_topic": false, ... },
+  "tier_used": "instant",
+  "model": "hermes3:8b",
+  "model_requested": "hermes3:8b",       // present because override was supplied
+  // ... rest of envelope unchanged
+}
+```
+
+もし、高性能/詳細なティアでタイムアウトが発生し、呼び出しがより高速なティアにフォールバックした場合、`env.model` は高速ティアで解決されたモデルとなり、`env.fallback_from` は `"workhorse"` となります。`env.model_requested` は依然として `"hermes3:8b"` のままとなり、`env.model !== env.model_requested` がフォールバックが発生したことを示すシグナルとなります。オーバーライドは、意図的に低コストなティアには引き継がれません。選択されたモデルが、そのティアの役割に適合しない場合もあります。
+
+### 過去のバージョン - v2.1.0の機能
+
+v2.2.0 の詳細については、[CHANGELOG.md](./CHANGELOG.md) および [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md) をご確認ください（フレームに依存しないトピックと、構造化された拒否）。
+
+## v2.2.0で追加
+
 ローカルの証拠収集機能に関する契約：主題に特化した内容と、構造化された拒否。マイナーな変更であり、v2.1.0からの呼び出し元は変更ありません。詳細は、[CHANGELOG.md](./CHANGELOG.md)と[docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md)を参照してください。
 
 - `ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep`における**主題に特化した抽出**：オプションで`frame: string`を入力し、構造化された`frame_alignment` / `on_topic` / `frame_addressed`の出力を行います。関連性の低いソースは、スキーマに変換するのではなく、フラグが立てられます。

package/README.md

@@ -27,6 +27,46 @@ No cloud. No telemetry. No "autonomous" anything. Every call shows its work.
 
 ---
 
+## New in v2.3.0
+
+Per-call model override across LLM-backed atom tools. Additive minor — v2.2.0 callers unchanged. Detailed entries in [CHANGELOG.md](./CHANGELOG.md) and [docs/release-notes/v2.3.0.md](./docs/release-notes/v2.3.0.md).
+
+- **Optional `model: string` input on 8 atom tools** — `ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep`, `ollama_research`, `ollama_corpus_answer`, `ollama_chat`, `ollama_code_citation`. The first attempt on the tool's tier runs against the caller-specified model; on timeout, the existing `TIER_FALLBACK` cascade resolves the cheaper tier's own model (NOT the caller's override). Composite/brief/pack tools deliberately do NOT accept `model` — atoms get per-call control, composites use tier defaults.
+- **New envelope field `model_requested?: string`** — present only when the override was supplied. Calibration-aware callers compare `model_requested` vs `model` to detect fallback substitution: `if (env.model_requested && env.model !== env.model_requested) { /* substitution */ }`. Empty / whitespace-only inputs throw `ZodError` at schema parse, not silent fallthrough.
+- **Bug fix — `src/version.ts` drift.** The runtime `VERSION` constant is now read from `package.json` at module load; v2.1.0 and v2.2.0 had shipped reporting the stale `"2.0.0"` identity string. New `tests/version.test.ts` locks `VERSION === pkg.version`.
+
+### Per-call model override (new in v2.3.0)
+
+```jsonc
+{
+  "tool": "ollama_classify",
+  "arguments": {
+    "text": "patch null pointer in auth",
+    "labels": ["feat", "fix", "chore"],
+    "frame": "what is the change kind?",
+    "model": "hermes3:8b"
+  }
+}
+```
+
+Envelope:
+
+```jsonc
+{
+  "result": { "label": "fix", "confidence": 0.9, "off_topic": false, ... },
+  "tier_used": "instant",
+  "model": "hermes3:8b",
+  "model_requested": "hermes3:8b",       // present because override was supplied
+  // ... rest of envelope unchanged
+}
+```
+
+If the workhorse/deep tier had timed out and the call had cascaded to the instant tier, `env.model` would be the instant tier's resolved model and `env.fallback_from` would be `"workhorse"` — `env.model_requested` would still be `"hermes3:8b"`, and `env.model !== env.model_requested` is the substitution signal. The override is deliberately NOT carried into the cheaper tier; the chosen model may not fit that tier's role at all.
+
+### Historical — v2.2.0 deliverables
+
+See [CHANGELOG.md](./CHANGELOG.md) and [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md) for the full v2.2.0 entry (frame-bound topicality + structured abstention).
+
 ## New in v2.2.0
 
 Local evidence-worker role contract: frame-bound topicality and structured abstention. Additive minor — v2.1.0 callers unchanged. Detailed entries in [CHANGELOG.md](./CHANGELOG.md) and [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md).

package/README.pt-BR.md

@@ -29,6 +29,46 @@ Sem nuvem. Sem telemetria. Sem nada "autônomo". Cada chamada mostra seu trabalh
 
 ## Novo no v2.2.0
 
+Substituição de modelo por chamada em todas as ferramentas "atom" que utilizam LLMs. Pequena alteração cumulativa — os chamadores da versão v2.2.0 permanecem inalterados. Detalhes nas seções [CHANGELOG.md](./CHANGELOG.md) e [docs/release-notes/v2.3.0.md](./docs/release-notes/v2.3.0.md).
+
+- **Entrada opcional `model: string` em 8 ferramentas "atom"** — `ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep`, `ollama_research`, `ollama_corpus_answer`, `ollama_chat`, `ollama_code_citation`. A primeira tentativa na camada da ferramenta utiliza o modelo especificado pelo chamador; em caso de timeout, a cascata existente `TIER_FALLBACK` resolve o modelo da própria camada mais econômica (e não a substituição do chamador). As ferramentas compostas/resumidas/de pacote *deliberadamente* não aceitam o parâmetro `model` — as ferramentas "atom" têm controle por chamada, enquanto as ferramentas compostas usam as configurações padrão da camada.
+- **Novo campo do "envelope" `model_requested?: string`** — presente apenas quando a substituição foi fornecida. Os chamadores que consideram a calibração comparam `model_requested` com `model` para detectar a substituição: `if (env.model_requested && env.model !== env.model_requested) { /* substituição */ }`. Entradas vazias ou contendo apenas espaços em branco geram um erro `ZodError` durante a análise do esquema, e não uma falha silenciosa.
+- **Correção de bug — desvio em `src/version.ts`.** A constante de tempo de execução `VERSION` agora é lida do arquivo `package.json` durante o carregamento do módulo; as versões v2.1.0 e v2.2.0 foram distribuídas com a string de identificação desatualizada `"2.0.0"`. Um novo arquivo `tests/version.test.ts` garante que `VERSION === pkg.version`.
+
+### Substituição de modelo por chamada (nova na v2.3.0)
+
+```jsonc
+{
+  "tool": "ollama_classify",
+  "arguments": {
+    "text": "patch null pointer in auth",
+    "labels": ["feat", "fix", "chore"],
+    "frame": "what is the change kind?",
+    "model": "hermes3:8b"
+  }
+}
+```
+
+Envelope:
+
+```jsonc
+{
+  "result": { "label": "fix", "confidence": 0.9, "off_topic": false, ... },
+  "tier_used": "instant",
+  "model": "hermes3:8b",
+  "model_requested": "hermes3:8b",       // present because override was supplied
+  // ... rest of envelope unchanged
+}
+```
+
+Se a camada "workhorse"/profunda tivesse atingido o tempo limite e a chamada tivesse sido direcionada para a camada instantânea, `env.model` seria o modelo resolvido da camada instantânea e `env.fallback_from` seria `"workhorse"` — `env.model_requested` ainda seria `"hermes3:8b"`, e `env.model !== env.model_requested` é o sinal de substituição. A substituição *deliberadamente* não é propagada para a camada mais econômica; o modelo escolhido pode não ser adequado para o papel dessa camada.
+
+### Histórico — entregas da v2.1.0
+
+Consulte [CHANGELOG.md](./CHANGELOG.md) e [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md) para a entrada completa da versão v2.2.0 (relevância contextual + abstenção estruturada).
+
+## Novo no v2.2.0
+
 Contrato de função local de processamento de evidências: relevância temática e abstenção estruturada. Pequena adição — as chamadas na v2.1.0 permanecem inalteradas. Detalhes em [CHANGELOG.md](./CHANGELOG.md) e [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md).
 
 - **Extração com base em contexto** em `ollama_extract`, `ollama_classify`, `ollama_summarize_fast`, `ollama_summarize_deep` — entrada opcional `frame: string` + saídas estruturadas `frame_alignment` / `on_topic` / `frame_addressed`. Fontes irrelevantes são sinalizadas em vez de serem parafraseadas no esquema.