feat: Fase 5 — Provider padrão + fallback automático por rate limit

- Default provider: openrouter (era thc)
- ProviderRateLimitError uniforme em base.py + 4 providers (429 e RESOURCE_EXHAUSTED)
- chat_completion_with_fallback: ordem configurável via ~/.thcrc, dedupe, thc fora da cadeia
- Integração em agent.py (run_agent) e chat.py (single-shot + REPL), com aviso ao usuário na troca
- Fix: NameError em messages_to_send no bloco single-shot (não existia nesse escopo)
- Guard: run_agent com fallback_order + config=None carrega config padrão via load_config()
- 18 testes novos (test_provider_fallback.py + test_providers_rate_limit.py)
- PROJECT_SPEC.md atualizado (Fase 3, 4, 5 concluídas; renumeração das fases seguintes)

116 testes, 1 skip esperado (test_alucinacao_fallback_llama_8b), 0 failures.

PROJECT_SPEC.md

@@ -4,7 +4,7 @@ INTEIRO antes de iniciar qualquer tarefa, e revisitar a seção de Guardrails
 e Lições Aprendidas durante a execução. Se algo aqui divergir do código
 real, pare e reporte — não assuma, não invente.
 
-Última atualização: 2026-07-23 — pós Fase 2.3 (Plan Mode)
+Última atualização: 2026-07-23 — pós Fase 5 (fallback automático de providers)
 
 ---
 
@@ -72,11 +72,19 @@ test_robustez_fase1b_2_1.py, test_agente_real_pexpect.py, test_tokens.py
 - [x] Fase 2.3 — Plan Mode (/plan, generate_plan(), on_round_complete,
       plan_mode_step_confirm em ~/.thcrc) — 50 testes OK
 - [ ] Fase 2.2 — Streaming (rich.live.Live) — ADIADA DE PROPÓSITO para o final
-- [ ] Fase 3 — Skills plug-and-play (~/.thc/skills/<nome>/SKILL.md)
-- [ ] Fase 4 — MCP (MCPTool, config em ~/.thcrc)
-- [ ] Fase 5 — Sub-agentes/orquestração (AgentTool, TaskCreateTool)
-- [ ] Fase 6 — Integrações de sistema (browser, LSP, git worktree)
-- [ ] Fase 7 — Empacotamento (pip install thc-cli, testes, CI)
+- [x] Fase 3 — Memória de longo prazo (MemoryStore, memory_write/read tools,
+      pinned entries, injetadas automaticamente no system prompt)
+      commit: f7583f1
+- [x] Fase 4 — Skills plug-and-play (SkillStore, /skills REPL, --skill CLI,
+      tools_allowed, system_prompt_extra) — 18 testes
+      commit: 8f1edf5
+- [x] Fase 5 — Provider padrão + fallback automático por rate limit
+      (default openrouter, ProviderRateLimitError, chat_completion_with_fallback,
+      ordem configurável em ~/.thcrc, thc fora da cadeia automática)
+- [ ] Fase 6 — MCP (MCPTool, config em ~/.thcrc)
+- [ ] Fase 7 — Sub-agentes/orquestração (AgentTool, TaskCreateTool)
+- [ ] Fase 8 — Integrações de sistema (browser, LSP, git worktree)
+- [ ] Fase 9 — Empacotamento (pip install thc-cli, testes, CI)
 
 ## 5. Lições aprendidas (atualizado pelo Claude a cada rodada)
 
@@ -84,6 +92,11 @@ test_robustez_fase1b_2_1.py, test_agente_real_pexpect.py, test_tokens.py
   free — sempre checar limites reais do provider antes de assumir bug de código.
 - Fase 2.3: nenhum deslize registrado nesta rodada. Diff, testes e módulo
   novo (plan.py) vieram exatamente como especificado.
+- Fase 5: diagnóstico do teste `test_alucinacao_fallback_llama_8b` foi só
+  parcialmente confirmado — as 3 execuções de verificação reproduziram apenas
+  rate limit (skip), não o cenário original de resposta malformada em bloco de
+  código. O parser de fallback ainda não foi validado contra esse formato
+  específico.
 
 ## 6. Ethos compartilhado (injetado no system prompt de todo provider)
 

tests/test_provider_fallback.py

@@ -0,0 +1,275 @@
+import json
+import unittest
+import unittest.mock
+
+from thc_cli.core.config import load_config, DEFAULT_PROVIDER_FALLBACK_ORDER
+from thc_cli.core.provider_fallback import chat_completion_with_fallback, ProviderRateLimitError
+from thc_cli.core.providers import PROVIDER_CLASSES
+
+
+class MockProvider:
+    def __init__(self, name, fail_with_rate_limit=False, fail_with_other=False):
+        self.name = name
+        self._fail_with_rate_limit = fail_with_rate_limit
+        self._fail_with_other = fail_with_other
+        self.calls = []
+
+    def chat_completion(self, messages, model, max_tokens=8192, temperature=0.7):
+        self.calls.append({
+            "messages": messages,
+            "model": model,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+        })
+        if self._fail_with_rate_limit:
+            raise ProviderRateLimitError(self.name, status_code=429, message="Rate limited")
+        if self._fail_with_other:
+            raise ValueError("Some other error")
+        return {
+            "choices": [{"message": {"role": "assistant", "content": f"response from {self.name}"}}],
+            "usage": {"prompt_tokens": 10, "completion_tokens": 20, "total_tokens": 30},
+        }
+
+
+def _make_mocks(failures=None):
+    failures = failures or {}
+    mocks = {}
+    for name, cls in PROVIDER_CLASSES.items():
+        mock = MockProvider(
+            name=name,
+            fail_with_rate_limit=failures.get(name, False),
+        )
+        mocks[name] = mock
+    return mocks
+
+
+class TestFallback(unittest.TestCase):
+    def test_fallback_usa_proximo_provider_em_rate_limit(self):
+        mocks = _make_mocks({"openrouter": True})
+        config = {"provider_fallback_order": ["openrouter", "mistral"]}
+        with unittest.mock.patch("thc_cli.core.provider_fallback.get_provider", side_effect=lambda n, _: mocks[n]):
+            result, used = chat_completion_with_fallback(
+                messages=[{"role": "user", "content": "oi"}],
+                model="mock-model",
+                max_tokens=16,
+                temperature=0.7,
+                config=config,
+                fallback_order=["openrouter", "mistral"],
+                provider_name="openrouter",
+            )
+        self.assertEqual(used, "mistral")
+        self.assertIn("mistral", result["choices"][0]["message"]["content"])
+        self.assertEqual(len(mocks["mistral"].calls), 1)
+
+    def test_fallback_pula_provider_ja_tentado(self):
+        mocks = _make_mocks({"openrouter": True, "mistral": True})
+        config = {"provider_fallback_order": ["openrouter", "mistral"]}
+        with unittest.mock.patch("thc_cli.core.provider_fallback.get_provider", side_effect=lambda n, _: mocks[n]):
+            with self.assertRaises(ProviderRateLimitError):
+                chat_completion_with_fallback(
+                    messages=[{"role": "user", "content": "oi"}],
+                    model="mock-model",
+                    max_tokens=16,
+                    temperature=0.7,
+                    config=config,
+                    fallback_order=["openrouter", "mistral"],
+                    provider_name="openrouter",
+                )
+        self.assertEqual(len(mocks["openrouter"].calls), 1)
+        self.assertEqual(len(mocks["mistral"].calls), 1)
+        self.assertEqual(len(mocks["groq"].calls), 0)
+
+    def test_fallback_mantem_provider_original_se_sem_erro(self):
+        mocks = _make_mocks()
+        config = {"provider_fallback_order": ["openrouter", "mistral"]}
+        with unittest.mock.patch("thc_cli.core.provider_fallback.get_provider", side_effect=lambda n, _: mocks[n]):
+            result, used = chat_completion_with_fallback(
+                messages=[{"role": "user", "content": "oi"}],
+                model="mock-model",
+                max_tokens=16,
+                temperature=0.7,
+                config=config,
+                fallback_order=["openrouter", "mistral"],
+                provider_name="openrouter",
+            )
+        self.assertEqual(used, "openrouter")
+        self.assertEqual(len(mocks["openrouter"].calls), 1)
+        self.assertEqual(len(mocks["mistral"].calls), 0)
+
+    def test_fallback_todos_falham_levanta_erro_claro(self):
+        mocks = _make_mocks({"openrouter": True, "mistral": True})
+        config = {"provider_fallback_order": ["openrouter", "mistral"]}
+        with unittest.mock.patch("thc_cli.core.provider_fallback.get_provider", side_effect=lambda n, _: mocks[n]):
+            with self.assertRaises(ProviderRateLimitError):
+                chat_completion_with_fallback(
+                    messages=[{"role": "user", "content": "oi"}],
+                    model="mock-model",
+                    max_tokens=16,
+                    temperature=0.7,
+                    config=config,
+                    fallback_order=["openrouter", "mistral"],
+                    provider_name="openrouter",
+                )
+
+    def test_fallback_ordem_configuravel_via_config(self):
+        mocks = _make_mocks({"mistral": True, "groq": True})
+        config = {"provider_fallback_order": ["mistral", "groq"]}
+        with unittest.mock.patch("thc_cli.core.provider_fallback.get_provider", side_effect=lambda n, _: mocks[n]):
+            with self.assertRaises(ProviderRateLimitError):
+                chat_completion_with_fallback(
+                    messages=[{"role": "user", "content": "oi"}],
+                    model="mock-model",
+                    max_tokens=16,
+                    temperature=0.7,
+                    config=config,
+                    fallback_order=["mistral", "groq"],
+                    provider_name="mistral",
+                )
+        self.assertEqual(len(mocks["groq"].calls), 1)
+
+    def test_fallback_provider_invalido_na_lista_e_ignorado(self):
+        mocks = _make_mocks({"openrouter": True})
+        config = {"provider_fallback_order": ["openrouter", "invalid_provider", "mistral"]}
+
+        def _get_provider(name, cfg):
+            if name not in mocks:
+                raise ValueError(f"Provider desconhecido: {name}")
+            return mocks[name]
+
+        with unittest.mock.patch("thc_cli.core.provider_fallback.get_provider", side_effect=_get_provider):
+            result, used = chat_completion_with_fallback(
+                messages=[{"role": "user", "content": "oi"}],
+                model="mock-model",
+                max_tokens=16,
+                temperature=0.7,
+                config=config,
+                fallback_order=["openrouter", "invalid_provider", "mistral"],
+                provider_name="openrouter",
+            )
+        self.assertEqual(used, "mistral")
+        self.assertEqual(len(mocks["mistral"].calls), 1)
+
+    def test_fallback_contexto_mensagens_repassado_integralmente_ao_proximo_provider(self):
+        mocks = _make_mocks({"openrouter": True})
+        config = {"provider_fallback_order": ["openrouter", "mistral"]}
+        messages = [
+            {"role": "system", "content": "you are helpful"},
+            {"role": "user", "content": "hello"},
+            {"role": "assistant", "content": "hi"},
+            {"role": "user", "content": "world"},
+        ]
+        with unittest.mock.patch("thc_cli.core.provider_fallback.get_provider", side_effect=lambda n, _: mocks[n]):
+            result, used = chat_completion_with_fallback(
+                messages=messages,
+                model="mock-model",
+                max_tokens=16,
+                temperature=0.7,
+                config=config,
+                fallback_order=["openrouter", "mistral"],
+                provider_name="openrouter",
+            )
+        self.assertEqual(used, "mistral")
+        self.assertEqual(len(mocks["mistral"].calls), 1)
+        self.assertEqual(mocks["mistral"].calls[0]["messages"], messages)
+
+    def test_config_default_provider_e_openrouter(self):
+        import tempfile
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            json.dump({"endpoint": "http://example.com"}, f)
+            path = f.name
+        with unittest.mock.patch("thc_cli.core.config.CONFIG_PATH") as mock_path:
+            mock_path.exists.return_value = True
+            mock_path.__str__ = lambda self: path
+            with unittest.mock.patch("builtins.open", unittest.mock.mock_open(read_data=json.dumps({"endpoint": "http://example.com"}))):
+                cfg = load_config()
+        self.assertEqual(cfg["provider"], "openrouter")
+
+    def test_config_le_provider_fallback_order_do_thcrc(self):
+        import tempfile
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            json.dump({"provider_fallback_order": ["mistral", "groq"]}, f)
+            path = f.name
+        with unittest.mock.patch("thc_cli.core.config.CONFIG_PATH") as mock_path:
+            mock_path.exists.return_value = True
+            mock_path.__str__ = lambda self: path
+            with unittest.mock.patch("builtins.open", unittest.mock.mock_open(read_data=json.dumps({"provider_fallback_order": ["mistral", "groq"]}))):
+                cfg = load_config()
+        self.assertEqual(cfg["provider_fallback_order"], ["mistral", "groq"])
+
+    def test_config_fallback_order_default_sem_thcrc(self):
+        import tempfile
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            json.dump({}, f)
+            path = f.name
+        with unittest.mock.patch("thc_cli.core.config.CONFIG_PATH") as mock_path:
+            mock_path.exists.return_value = True
+            mock_path.__str__ = lambda self: path
+            with unittest.mock.patch("builtins.open", unittest.mock.mock_open(read_data=json.dumps({}))):
+                cfg = load_config()
+        self.assertEqual(cfg["provider_fallback_order"], DEFAULT_PROVIDER_FALLBACK_ORDER)
+
+    def test_fallback_http_429_via_mensagem(self):
+        import httpx
+        mocks = _make_mocks()
+        mocks["openrouter"]._fail_with_rate_limit = False
+        mocks["openrouter"]._fail_with_other = True
+        
+        request = httpx.Request("POST", "http://example.com")
+        response = httpx.Response(429, request=request, text="Too Many Requests")
+        mocks["openrouter"].chat_completion = unittest.mock.Mock(side_effect=httpx.HTTPStatusError("429", request=request, response=response))
+        
+        config = {"provider_fallback_order": ["openrouter", "mistral"]}
+        with unittest.mock.patch("thc_cli.core.provider_fallback.get_provider", side_effect=lambda n, _: mocks[n]):
+            result, used = chat_completion_with_fallback(
+                messages=[{"role": "user", "content": "oi"}],
+                model="mock-model",
+                max_tokens=16,
+                temperature=0.7,
+                config=config,
+                fallback_order=["openrouter", "mistral"],
+                provider_name="openrouter",
+            )
+        self.assertEqual(used, "mistral")
+
+    def test_fallback_nao_propaga_erro_nao_rate_limit(self):
+        mocks = _make_mocks({"openrouter": False})
+        mocks["openrouter"]._fail_with_rate_limit = False
+        mocks["openrouter"]._fail_with_other = True
+        mocks["openrouter"].chat_completion = unittest.mock.Mock(side_effect=ValueError("auth failed"))
+        config = {"provider_fallback_order": ["openrouter", "mistral"]}
+        with unittest.mock.patch("thc_cli.core.provider_fallback.get_provider", side_effect=lambda n, _: mocks[n]):
+            with self.assertRaises(ValueError):
+                chat_completion_with_fallback(
+                    messages=[{"role": "user", "content": "oi"}],
+                    model="mock-model",
+                    max_tokens=16,
+                    temperature=0.7,
+                    config=config,
+                    fallback_order=["openrouter", "mistral"],
+                    provider_name="openrouter",
+                )
+        self.assertEqual(len(mocks["mistral"].calls), 0)
+
+    def test_chat_single_shot_fallback_sucesso(self):
+        from thc_cli.commands.chat import _provider_chat_with_fallback
+        mocks = _make_mocks({"openrouter": True})
+        config = {"provider_fallback_order": ["openrouter", "mistral"], "provider_keys": {}}
+        with unittest.mock.patch("thc_cli.core.provider_fallback.get_provider", side_effect=lambda n, _: mocks[n]):
+            result, used = _provider_chat_with_fallback(
+                provider=mocks["openrouter"],
+                provider_name="openrouter",
+                messages=[{"role": "user", "content": "oi"}],
+                model="mock-model",
+                mode="medium",
+                web=False,
+                max_tokens=16,
+                temperature=0.7,
+                config=config,
+                fallback_order=["openrouter", "mistral"],
+            )
+        self.assertEqual(used, "mistral")
+        self.assertIn("mistral", result["choices"][0]["message"]["content"])
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

tests/test_providers_rate_limit.py

@@ -0,0 +1,112 @@
+import json
+import unittest
+import unittest.mock
+
+import httpx
+
+from thc_cli.core.agent import run_agent
+from thc_cli.core.provider_fallback import ProviderRateLimitError
+from thc_cli.core.providers import PROVIDER_CLASSES
+from thc_cli.core.providers.groq_provider import GroqProvider
+from thc_cli.core.providers.mistral_provider import MistralProvider
+from thc_cli.core.providers.openrouter_provider import OpenRouterProvider
+from thc_cli.core.providers.gemini_provider import GeminiProvider
+
+
+def _make_429_response():
+    request = httpx.Request("POST", "https://example.com")
+    return httpx.Response(429, request=request, text="Too Many Requests")
+
+
+class TestProviderRateLimit(unittest.TestCase):
+    def test_openrouter_rate_limit(self):
+        provider = OpenRouterProvider(api_key="fake-key")
+        with unittest.mock.patch("httpx.Client.post", return_value=_make_429_response()):
+            with self.assertRaises(ProviderRateLimitError) as ctx:
+                provider.chat_completion(
+                    messages=[{"role": "user", "content": "oi"}],
+                    model="google/gemma-4-31b-it:free",
+                )
+        self.assertEqual(ctx.exception.provider_name, "openrouter")
+        self.assertEqual(ctx.exception.status_code, 429)
+
+    def test_mistral_rate_limit(self):
+        provider = MistralProvider(api_key="fake-key")
+        with unittest.mock.patch("httpx.Client.post", return_value=_make_429_response()):
+            with self.assertRaises(ProviderRateLimitError) as ctx:
+                provider.chat_completion(
+                    messages=[{"role": "user", "content": "oi"}],
+                    model="mistral-small-latest",
+                )
+        self.assertEqual(ctx.exception.provider_name, "mistral")
+        self.assertEqual(ctx.exception.status_code, 429)
+
+    def test_groq_rate_limit(self):
+        provider = GroqProvider(api_key="fake-key")
+        with unittest.mock.patch("httpx.Client.post", return_value=_make_429_response()):
+            with self.assertRaises(ProviderRateLimitError) as ctx:
+                provider.chat_completion(
+                    messages=[{"role": "user", "content": "oi"}],
+                    model="llama-3.1-8b-instant",
+                )
+        self.assertEqual(ctx.exception.provider_name, "groq")
+        self.assertEqual(ctx.exception.status_code, 429)
+
+    def test_gemini_rate_limit_via_status(self):
+        provider = GeminiProvider(api_key="fake-key")
+        with unittest.mock.patch("httpx.Client.post", return_value=_make_429_response()):
+            with self.assertRaises(ProviderRateLimitError) as ctx:
+                provider.chat_completion(
+                    messages=[{"role": "user", "content": "oi"}],
+                    model="gemini-3.5-flash",
+                )
+        self.assertEqual(ctx.exception.provider_name, "gemini")
+        self.assertEqual(ctx.exception.status_code, 429)
+
+    def test_gemini_rate_limit_via_body(self):
+        provider = GeminiProvider(api_key="fake-key")
+        response = httpx.Response(
+            200,
+            request=httpx.Request("POST", "https://example.com"),
+            json={
+                "error": {"status": "RESOURCE_EXHAUSTED", "message": "quota exceeded"},
+            },
+        )
+        with unittest.mock.patch("httpx.Client.post", return_value=response):
+            with self.assertRaises(ProviderRateLimitError) as ctx:
+                provider.chat_completion(
+                    messages=[{"role": "user", "content": "oi"}],
+                    model="gemini-3.5-flash",
+                )
+        self.assertEqual(ctx.exception.provider_name, "gemini")
+        self.assertEqual(ctx.exception.status_code, 429)
+
+    def test_run_agent_fallback_success_with_config_none(self):
+        fake_reply = {
+            "choices": [{"message": {"role": "assistant", "content": "ok"}}],
+            "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2},
+        }
+        fake_provider = unittest.mock.Mock()
+        fake_provider.name = "openrouter"
+        fake_provider.chat_completion.return_value = fake_reply
+
+        def _fake_get_provider(name, config):
+            return fake_provider
+
+        with unittest.mock.patch("thc_cli.core.agent.get_provider", side_effect=_fake_get_provider):
+            with unittest.mock.patch("thc_cli.core.provider_fallback.get_provider", side_effect=_fake_get_provider):
+                with unittest.mock.patch("thc_cli.core.agent.load_config", return_value={"provider_keys": {}}):
+                    with unittest.mock.patch("thc_cli.core.agent.MemoryStore"):
+                        reply = run_agent(
+                            provider=fake_provider,
+                            messages=[{"role": "user", "content": "oi"}],
+                            model="mock",
+                            fallback_order=["openrouter"],
+                            config=None,
+                            max_rounds=1,
+                        )
+        self.assertIn("ok", reply)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

thc_cli/commands/chat.py

@@ -13,7 +13,9 @@ from ..core import print_thinking_spinner, print_diff, confirm
 from ..core.agent import run_agent
 from ..core.memory import MemoryStore
 from ..core.plan import generate_plan
+from ..core.provider_fallback import chat_completion_with_fallback
 from ..core.providers import get_provider
+from ..core.providers.base import ProviderRateLimitError
 from ..core.session import list_sessions, load_session, save_session
 from ..core.skills import SkillStore
 from ..core.system_prompt import build_base_system_prompt
@@ -101,6 +103,25 @@ def _provider_chat(provider, messages, model, mode, web, max_tokens=8192, temper
     )
 
 
+def _provider_chat_with_fallback(provider, provider_name, messages, model, mode, web, max_tokens, temperature, config, fallback_order):
+    if _is_thc_provider(provider):
+        return _provider_chat(provider, messages, model, mode, web, max_tokens, temperature), provider_name
+    
+    if not fallback_order:
+        return _provider_chat(provider, messages, model, mode, web, max_tokens, temperature), provider_name
+    
+    def _on_fallback(from_name, to_name):
+        console.print(f"[yellow]⚠ {from_name} atingiu rate limit — mudando para {to_name}[/yellow]")
+    try:
+        result, used_name = chat_completion_with_fallback(
+            messages, model, max_tokens, temperature, config or {},
+            fallback_order, provider_name, on_fallback=_on_fallback,
+        )
+        return result, used_name
+    except ProviderRateLimitError as e:
+        raise ProviderRateLimitError(provider_name, status_code=getattr(e, 'status_code', None), message=str(e))
+
+
 def _format_elapsed(seconds: float) -> str:
     minutes = int(seconds // 60)
     secs = int(seconds % 60)
@@ -200,6 +221,8 @@ def run(args, config):
                     on_tool_result=on_tool_result,
                     on_thinking=on_thinking,
                     skill=active_skill,
+                    fallback_order=config.get("provider_fallback_order", []),
+                    config=config,
                 )
             except Exception as e:
                 print(f"Erro: {e}", file=sys.stderr)
@@ -212,17 +235,25 @@ def run(args, config):
                 web_msg = _build_web_search_system_message(args.prompt)
                 if web_msg:
                     messages.append(web_msg)
-            messages.append({"role": "user", "content": args.prompt})
+                messages.append({"role": "user", "content": args.prompt})
             try:
                 with print_thinking_spinner():
-                    result = _provider_chat(
-                        provider=provider,
-                        messages=messages,
-                        model=model,
-                        mode=mode,
-                        web=web,
-                        max_tokens=max_tokens,
-                    )
+                    try:
+                        result, used_name = _provider_chat_with_fallback(
+                            provider=provider,
+                            provider_name=provider_name,
+                            messages=messages,
+                            model=model,
+                            mode=mode,
+                            web=web,
+                            max_tokens=max_tokens,
+                            temperature=0.7,
+                            config=config,
+                            fallback_order=config.get("provider_fallback_order", []),
+                        )
+                    except ProviderRateLimitError as e:
+                        console.print(f"[red]Erro: todos os providers da lista de fallback falharam ({e})[/red]")
+                        raise
                 reply = result["choices"][0]["message"]["content"]
             except Exception as e:
                 print(f"Erro: {e}", file=sys.stderr)
@@ -518,6 +549,8 @@ def run(args, config):
                     on_thinking=on_thinking,
                     on_round_complete=_on_round_complete,
                     skill=active_skill,
+                    fallback_order=config.get("provider_fallback_order", []),
+                    config=config,
                 )
                 history.append({"role": "assistant", "content": reply})
             else:
@@ -529,14 +562,29 @@ def run(args, config):
                             web_msg = _build_web_search_system_message(last_user_message)
                             if web_msg:
                                 messages_to_send.insert(1, web_msg)
-                    result = _provider_chat(
-                        provider=provider,
-                        messages=messages_to_send,
-                        model=model,
-                        mode=mode,
-                        web=web,
-                        max_tokens=max_tokens,
-                    )
+                    try:
+                        result, used_name = _provider_chat_with_fallback(
+                            provider=provider,
+                            provider_name=provider_name,
+                            messages=messages_to_send,
+                            model=model,
+                            mode=mode,
+                            web=web,
+                            max_tokens=max_tokens,
+                            temperature=0.7,
+                            config=config,
+                            fallback_order=config.get("provider_fallback_order", []),
+                        )
+                    except ProviderRateLimitError as e:
+                        console.print(f"[red]Erro: todos os providers da lista de fallback falharam ({e})[/red]")
+                        raise
+                    if used_name and used_name != provider_name:
+                        try:
+                            provider_name = used_name
+                            provider = get_provider(used_name, config)
+                            _banner(model, mode, web, agent_mode, plan_mode, provider_name)
+                        except Exception as e:
+                            console.print(f"[red]Erro ao aplicar fallback para {used_name}: {e}[/red]")
                 reply = result["choices"][0]["message"]["content"]
                 history.append({"role": "assistant", "content": reply})
             _render_reply(reply)

thc_cli/core/agent.py

@@ -2,7 +2,11 @@ import json
 import re
 from typing import Optional
 
+from .config import load_config
 from .memory import MemoryStore
+from .provider_fallback import chat_completion_with_fallback
+from .providers import get_provider
+from .providers.base import ProviderRateLimitError
 from .system_prompt import build_base_system_prompt
 from .tools import ALL_TOOLS, TOOLS_BY_NAME
 
@@ -117,6 +121,8 @@ def run_agent(
     on_thinking: Optional[callable] = None,
     on_round_complete: Optional[callable] = None,
     skill: Optional[dict] = None,
+    fallback_order: list[str] = None,
+    config: dict = None,
 ) -> str:
     tools_to_use = TOOLS_BY_NAME
     if skill and skill.get("tools_allowed"):
@@ -137,9 +143,41 @@ def run_agent(
     if skill and skill.get("system_prompt_extra"):
         system_prompt += "\n\n## Skill ativa: " + skill["name"] + "\n" + skill["system_prompt_extra"]
     messages = [{"role": "system", "content": system_prompt}] + list(messages)
+
+    state = {
+        "provider": provider,
+        "provider_name": getattr(provider, "name", None),
+    }
+
+    def _do_chat(messages_for_call):
+        if fallback_order and state["provider_name"] and state["provider_name"] != "thc":
+            def _on_fallback(from_name, to_name):
+                if on_tool_result:
+                    on_tool_result("fallback", f"⚠ {from_name} atingiu rate limit — mudando para {to_name}")
+            try:
+                result, used_name = chat_completion_with_fallback(
+                    messages=messages_for_call,
+                    model=model,
+                    max_tokens=max_tokens,
+                    temperature=temperature,
+                    config=config or load_config(),
+                    fallback_order=fallback_order,
+                    provider_name=state["provider_name"],
+                    on_fallback=_on_fallback,
+                )
+                if used_name != state["provider_name"]:
+                    state["provider_name"] = used_name
+                    state["provider"] = get_provider(used_name, config or {})
+                return result
+            except ProviderRateLimitError:
+                if on_tool_result:
+                    on_tool_result("fallback", "Erro: todos os providers da lista de fallback falharam")
+                raise
+        return _provider_chat_completion(state["provider"], messages_for_call, model, mode, web, max_tokens, temperature)
+
     for _ in range(max_rounds):
         messages = _truncate_history(messages)
-        result = _provider_chat_completion(provider, messages, model, mode, web, max_tokens, temperature)
+        result = _do_chat(messages)
         assistant_message = result["choices"][0]["message"]["content"]
         messages.append({"role": "assistant", "content": assistant_message})
         thinking = TOOL_CALL_PATTERN.split(assistant_message)[0].strip()
@@ -154,7 +192,7 @@ def run_agent(
             for retry in range(2):
                 error_msg = "Seu último tool_call não é JSON válido ou está malformado. Responda novamente APENAS com o bloco ```tool_call``` corrigido."
                 messages.append({"role": "user", "content": error_msg})
-                retry_result = _provider_chat_completion(provider, messages, model, mode, web, max_tokens, temperature)
+                retry_result = _do_chat(messages)
                 retry_message = retry_result["choices"][0]["message"]["content"]
                 messages.append({"role": "assistant", "content": retry_message})
                 tool_calls = _extract_tool_calls(retry_message)

thc_cli/core/config.py

@@ -4,6 +4,8 @@ from pathlib import Path
 
 DEFAULT_ENDPOINT = "https://hulktoigo-thcllm.hf.space"
 CONFIG_PATH = Path.home() / ".thcrc"
+DEFAULT_PROVIDER_FALLBACK_ORDER = ["openrouter", "mistral", "groq", "gemini"]
+_VALID_PROVIDERS = {"thc", "groq", "mistral", "gemini", "openrouter"}
 
 
 def load_config() -> dict:
@@ -18,7 +20,7 @@ def load_config() -> dict:
     
     endpoint = os.environ.get("THC_ENDPOINT") or file_config.get("endpoint") or DEFAULT_ENDPOINT
     api_key = os.environ.get("THC_API_KEY") or file_config.get("api_key")
-    provider = os.environ.get("THC_PROVIDER") or file_config.get("provider", "thc")
+    provider = os.environ.get("THC_PROVIDER") or file_config.get("provider", DEFAULT_PROVIDER_FALLBACK_ORDER[0])
     provider_keys = dict(file_config.get("provider_keys", {}))
     for key_name, env_name in [
         ("groq", "GROQ_API_KEY"),
@@ -29,9 +31,13 @@ def load_config() -> dict:
         if env_name in os.environ:
             provider_keys[key_name] = os.environ[env_name]
     
+    raw_fallback_order = file_config.get("provider_fallback_order", DEFAULT_PROVIDER_FALLBACK_ORDER)
+    provider_fallback_order = [p for p in raw_fallback_order if p in _VALID_PROVIDERS]
+    
     return {
         "endpoint": endpoint,
         "api_key": api_key,
         "provider": provider,
         "provider_keys": provider_keys,
+        "provider_fallback_order": provider_fallback_order,
     }

thc_cli/core/provider_fallback.py

@@ -0,0 +1,61 @@
+from typing import Optional, Callable, List
+
+from .providers import get_provider, PROVIDER_CLASSES
+from .providers.base import ProviderRateLimitError
+
+
+def chat_completion_with_fallback(
+    messages: list[dict],
+    model: str,
+    max_tokens: int,
+    temperature: float,
+    config: dict,
+    fallback_order: list[str],
+    provider_name: str,
+    on_fallback: Optional[Callable[[str, str], None]] = None,
+) -> tuple[dict, str]:
+    tried: List[str] = []
+    order = [provider_name] + [p for p in fallback_order if p != provider_name]
+    last_error: Optional[ProviderRateLimitError] = None
+
+    for name in order:
+        if name in tried:
+            continue
+        tried.append(name)
+        try:
+            provider = get_provider(name, config)
+            result = provider.chat_completion(
+                messages=messages,
+                model=model,
+                max_tokens=max_tokens,
+                temperature=temperature,
+            )
+            if name != provider_name and on_fallback:
+                on_fallback(provider_name, name)
+            return result, name
+        except ProviderRateLimitError as e:
+            last_error = e
+            continue
+        except ValueError as e:
+            if "desconhecido" in str(e):
+                continue
+            raise
+        except Exception as e:
+            status_code = getattr(getattr(e, "response", None), "status_code", None)
+            msg = str(e).lower()
+            is_rate = status_code == 429 or any(k in msg for k in [
+                "rate limit", "quota", "too many requests", "resource_exhausted", "resourseexhausted"
+            ])
+            if is_rate:
+                last_error = ProviderRateLimitError(
+                    provider_name=name,
+                    status_code=status_code,
+                    message=str(e),
+                )
+                continue
+            raise
+
+    raise last_error or ProviderRateLimitError(
+        provider_name=provider_name,
+        message="Todos os providers da lista de fallback falharam",
+    )

thc_cli/core/providers/base.py

@@ -1,3 +1,10 @@
+class ProviderRateLimitError(Exception):
+    def __init__(self, provider_name: str, status_code: int = None, message: str = ""):
+        self.provider_name = provider_name
+        self.status_code = status_code
+        super().__init__(message or f"{provider_name}: rate limit ou quota excedida")
+
+
 class BaseProvider:
     name: str = ""
 

thc_cli/core/providers/gemini_provider.py

@@ -4,7 +4,7 @@ from typing import Optional
 
 import httpx
 
-from .base import BaseProvider
+from .base import BaseProvider, ProviderRateLimitError
 
 
 GEMINI_MODELS = [
@@ -59,6 +59,14 @@ class GeminiProvider(BaseProvider):
         url = f"{self.endpoint}/{model}:generateContent?key={self.api_key}"
         with httpx.Client(timeout=120.0) as client:
             resp = client.post(url, json=payload, headers={"Content-Type": "application/json"})
+        if resp.status_code == 429:
+            raise ProviderRateLimitError(self.name, status_code=resp.status_code, message="Rate limited")
+        try:
+            data = resp.json()
+        except Exception:
+            data = {}
+        if isinstance(data.get("error"), dict) and data["error"].get("status") == "RESOURCE_EXHAUSTED":
+            raise ProviderRateLimitError(self.name, status_code=429, message="RESOURCE_EXHAUSTED")
         resp.raise_for_status()
         data = resp.json()
         text = data["candidates"][0]["content"]["parts"][0]["text"]

thc_cli/core/providers/groq_provider.py

@@ -1,7 +1,7 @@
 import httpx
 from typing import Optional
 
-from .base import BaseProvider
+from .base import BaseProvider, ProviderRateLimitError
 
 
 GROQ_MODELS = [
@@ -37,6 +37,8 @@ class GroqProvider(BaseProvider):
         }
         with httpx.Client(timeout=120.0) as client:
             resp = client.post(self.endpoint, json=payload, headers=headers)
+        if resp.status_code == 429:
+            raise ProviderRateLimitError(self.name, status_code=resp.status_code, message="Rate limited")
         resp.raise_for_status()
         return resp.json()
 

thc_cli/core/providers/mistral_provider.py

@@ -1,6 +1,6 @@
 import httpx
 
-from .base import BaseProvider
+from .base import BaseProvider, ProviderRateLimitError
 
 
 MISTRAL_MODELS = [
@@ -36,6 +36,8 @@ class MistralProvider(BaseProvider):
         }
         with httpx.Client(timeout=120.0) as client:
             resp = client.post(self.endpoint, json=payload, headers=headers)
+        if resp.status_code == 429:
+            raise ProviderRateLimitError(self.name, status_code=resp.status_code, message="Rate limited")
         resp.raise_for_status()
         return resp.json()
 

thc_cli/core/providers/openrouter_provider.py

@@ -1,6 +1,6 @@
 import httpx
 
-from .base import BaseProvider
+from .base import BaseProvider, ProviderRateLimitError
 
 
 OPENROUTER_MODELS = [
@@ -36,6 +36,8 @@ class OpenRouterProvider(BaseProvider):
         }
         with httpx.Client(timeout=120.0) as client:
             resp = client.post(self.endpoint, json=payload, headers=headers)
+        if resp.status_code == 429:
+            raise ProviderRateLimitError(self.name, status_code=resp.status_code, message="Rate limited")
         resp.raise_for_status()
         return resp.json()