brito-cli 0.7.5 → 0.9.0

package/README.md

@@ -18,7 +18,7 @@ Brito is an agent for software development. Use it in the terminal (`brito-cli`
 - **Wide coverage.** TypeScript/JavaScript, Python and the script blocks of `.svelte`, `.vue` and `.astro` components. Import aliases (`tsconfig` paths, `package.json` imports, SvelteKit's `$lib`) become real edges. Files ignored by `.gitignore` stay out.
 - **Skills that learn on their own, on probation.** After a task that tripped or was corrected, Brito reflects and creates a skill *in trial* without interrupting you. A skill proves itself by use: 3 clean uses promote it, 2 stumbles archive it (recoverable). Anything risky, or any change to a skill you approved, still waits for your `/skills approve`. `BRITO_SKILLS=ask` restores approval-for-everything; `off` disables learning.
 - **Safety rails for what gets learned.** A lint rejects secrets, credentials embedded in URLs, `curl | sh` and prompt-injection phrasing, and **warns about destructive commands** (see below).
-- **Permission modes.** manual, auto-edits, plan and "everything allowed" (`Shift+Tab` cycles them). Autonomous skills do not depend on the mode: they are created in trial and judged by results.
+- **Permission modes and rules.** manual, auto-edits, plan and "everything allowed" (`Shift+Tab` cycles them), plus `allow`/`deny` rules per command or path (see [Permission rules](#permission-rules)). Editing a file requires having read it in the session, unchanged since. Autonomous skills do not depend on the mode: they are created in trial and judged by results.
 - **Two backends, one interface.** Use an Anthropic API key, or your Claude Code subscription through the `claude` CLI. Brito never reads or sends your subscription token.
 - **Terminal or desktop app.** `npm i -g brito-cli` gives you the `brito` command; the desktop app is a native executable with a window (projects and sessions in a sidebar, chat, permission prompts), no Node or terminal needed. See [Install](#install).
 - **Images.** Drag an image file into the prompt (or paste its path) and it is attached to the turn: PNG, JPEG, GIF or WebP, up to 5 MB.
@@ -73,6 +73,17 @@ flowchart LR
 
 The lint **rejects** secrets/tokens, absolute user paths, credentials in URLs (`user:password@host`), `curl | sh`, and instructions to override rules or skip approval. It **warns** (without blocking) about commands that destroy data: removing database or data files, `DROP`/`TRUNCATE`, `DELETE` without `WHERE`, migration resets, `git reset --hard`, force-push, Docker volume removal. A skill is a standing instruction, so a step that was only safe in the state of one moment must not silently become the default.
 
+## Local model (optional)
+
+`brito slm pull` downloads a small local model (Qwen3-4B-Instruct-2507 Q4_K_M, Apache-2.0) to `~/.brito/models` through the optional `node-llama-cpp` dependency. `brito slm` shows the status and `brito slm rm` deletes it. Once downloaded it is used for:
+
+- **Skill learning**: the reflection runs locally with grammar-constrained JSON and falls back to the usual model on any failure.
+- **`digest` tool**: a scout and refiner for long texts. The local model picks the blocks most related to your objective and proposes excerpts; code then checks every quote against the source and drops what is not there, so the main model gets a small markdown draft with verified quotes and page numbers.
+
+- **Fallback when Claude runs out**: chain Claude → `qwen` profile → local SLM, with the full agent loop and tools (same permissions). It is temporary: after a window (the reset time reported by the error, else 10 min, or 60 min for quota/auth; `BRITO_FALLBACK_MINUTES` overrides) the next turn tries Claude again. `/fallback` shows when. A 4B model errs more with tools: use it to keep going, not for big tasks. `BRITO_SLM_FALLBACK=off` removes it from the chain; `BRITO_SLM_CTX` sets its context.
+
+`BRITO_SLM=off` disables it; `BRITO_SLM_MODEL` points to another GGUF (`hf:` URI or file path).
+
 ## Install
 
 ### Terminal (`brito-cli`)
@@ -103,7 +114,9 @@ export ANTHROPIC_API_KEY=sk-ant-...      # Anthropic API
 
 ### Desktop app (executable)
 
-The same agent in a window: projects and sessions in a sidebar, chat with markdown, collapsible tool calls, permission prompts, and pickers for model, effort and permission mode. It needs neither Node nor a terminal.
+The same agent in a window: projects and sessions in a sidebar, streaming chat with markdown and code copy, tool cards with diffs for edits, a pinned task list, permission prompts with a diff ("allow once / this session / always in this project"), and pickers for model, effort and permission mode. It needs neither Node nor a terminal (on Windows the code graph still needs Node.js 20+).
+
+Beyond the chat: type `/` for commands and skills, `@` to pick project files (or drop files on the box), `Ctrl/Cmd+K` for the command palette (actions and full-text search across sessions), panels for Skills, Agents, the code Graph, Memory and Changed files, an engine badge (cloud / endpoint / local) with a fallback warning, light/dark theme and export to markdown.
 
 ![Brito desktop app answering a question with the code graph](docs/images/desktop-app.png)
 
@@ -130,6 +143,9 @@ cd your-project
 brito                       # opens the REPL
 brito "who calls parseConfig?"   # single prompt, no REPL
 brito index                 # (re)index the graph; it is also kept up to date automatically
+brito -c                    # resume the most recent session in this project
+brito sessions              # list saved sessions; resume one with brito --resume <id>
+brito slm pull              # (optional) download the local model used by digest and skill learning
 brito query "MATCH (c:Symbol {kind:'component'})-[:CALLS]->(f:Symbol) RETURN c.file, f.name LIMIT 5"
 ```
 
@@ -150,10 +166,15 @@ OK: 20 arquivos, 66 símbolos, 54 chamadas, 17 imports | +0 ~0 -0 =20 (28ms)
 | `/fallback` | shows the main model and the fallback (qwen), and whether the switch already happened |
 | `/modo` or `Shift+Tab` | switch permission mode: manual → auto-edits → plan → bypass ("everything allowed") |
 | `/skills` | list skills · `pending` · `approve <name>` · `reject <name>` · `consolidate` · `rm <name>` · `promote <name>` |
+| `/permissions` | list permission rules · `allow <rule>` · `deny <rule>` |
 | `/learn` | extract skills from the last turn now |
+| `/grill-me`, `/grill-with-docs`, `/wayfinder`, `/grill-diff` | built-in manual skills: interview you until the idea is firm (`--um` = one question per message), also save decisions with `remember`, map big work and delegate, question the current diff |
+| `/skills suggest <task>` | rank skills (built-ins included) by relevance to a task |
 | `/agents`, `/tools`, `/index`, `/context` | inspect subagents, tools, the index and the context window |
 | `!command` | run a shell command directly, without calling the model |
-| `/clear`, `/exit` | clear the conversation, quit |
+| `/todos` | show the session's task list (the agent keeps it with `todo_write` on multi-step tasks) |
+| `/sessions` | list this project's saved sessions |
+| `/clear`, `/exit` | start another conversation (the previous one stays saved), quit |
 
 ## What the graph indexes
 
@@ -163,6 +184,26 @@ OK: 20 arquivos, 66 símbolos, 54 chamadas, 17 imports | +0 ~0 -0 =20 (28ms)
 - **Backend languages:** the graph holds classes/interfaces/structs/traits/enums/modules, functions and methods (`Class.method`), calls and imports. Imports name a package, not a path, so Brito matches them against the end of your files' paths (`com.acme.Repo` ↔ `src/main/java/com/acme/Repo.java`; PHP PSR-4 namespaces; Rust `use crate::…`; Ruby `require`/`require_relative`; Go packages through the `go.mod` module path). External packages (`java.util`, `serde`, `github.com/gin-gonic/gin`) never match and create no edges. There is no type inference: a call like `userRepository.save()` is linked by matching the receiver name to a type in the project (`UserRepository`), `this`/`self`/receivers resolve to the enclosing class, and a bare call inside a class tries the class's own methods first.
 - **Not yet:** `extends` by package (`@tsconfig/node20`), sibling-workspace `exports`, and function references without a call in a template (`onclick={fn}`). Calls are resolved statically with name-based fallbacks, so dynamic dispatch and reflection are not captured.
 
+## Permission rules
+
+To stop approving the same command every time (without resorting to "everything allowed"), declare rules in `.brito/settings.json` (per project, can be committed), `.brito/settings.local.json` (just you) or `~/.brito/settings.json` (all projects). The lists add up.
+
+```json
+{
+  "permissions": {
+    "allow": ["bash(npm test:*)", "bash(npm run typecheck)", "bash(git status:*)", "edit_file(src/**)"],
+    "deny": ["bash(git push:*)", "bash(rm -rf*)", "read_file(.env*)"]
+  }
+}
+```
+
+- `tool` matches any use; `tool(pattern)` narrows it. In `bash`, `*` matches anything and a trailing `:*` matches the prefix alone or followed by arguments (`git status:*` allows `git status --short`, not `git statusx`). In paths, `*` does not cross directories and `**` does.
+- **`allow` skips the prompt** in manual and auto-edits modes. Plan mode still blocks.
+- **`deny` always blocks**, even in "everything allowed".
+- A compound command is allowed only if **every piece** (`&&`, `||`, `;`, `|`) matches a rule: `bash(npm test*)` does not allow `npm test && rm -rf ~`. Commands with `$(...)`, backticks or redirection to a file are never allowed by a rule; `2>&1` and `> /dev/null` are fine.
+- The rules also apply to the `claude` CLI's Bash, Edit and Write when Brito runs on your subscription.
+- `/permissions` lists the rules; `/permissions allow bash(npm test:*)` writes to `.brito/settings.json`.
+
 ## Databases and other sensitive resources
 
 Brito has **no database drivers and connects to nothing on its own**. When it needs to touch a database, it uses your project's own tooling through the shell, under the permission mode you chose. Because every project is different (a local file, a remote server, a container), declare the sensitive parts in `BRITO.md` (or `CLAUDE.md` / `AGENTS.md`), which is read into the system prompt:
@@ -220,6 +261,15 @@ With Claude as the main model (API or `claude` CLI), the `qwen` profile is the a
 - Without `ANTHROPIC_API_KEY` and without the `claude` CLI, Brito opens straight on Qwen, with a warning. If the fallback is not ready, the usual error includes why (e.g. `BRITO_QWEN_API_KEY` is missing). An invalid `qwen` profile is still an error, never a silent fallback.
 - `/fallback` shows the state. In the desktop app, send `/fallback` as a message; the status bar shows Qwen while the fallback is active.
 
+### Orchestrator mode: Claude plans, Qwen implements
+
+`/orquestrar on` keeps Claude as the main model but hands the implementation to an endpoint profile (`qwen` by default). Claude writes the spec and the task list to `spec/<feature>/spec.md` and `spec/<feature>/tasks.md` (`spec_save` tool), waits for your approval, and only then sends one task at a time to the `implement` tool, checking off in `tasks.md` the ones that pass its review. It loses its file-editing tools (`write_file`/`edit_file`, or `Edit`/`Write`/`MultiEdit`/`NotebookEdit` in `claude` CLI mode): its only write is `spec_save`, which can only write those two files. It keeps reading, the graph and `bash` to check the work.
+
+- The implementer runs in an isolated context (it does not see the conversation), with the graph of the symbols passed in `focus`. Its edits and commands follow the permission mode, and in `claude` CLI mode they are approved in the terminal just like Claude's.
+- When it finishes, the tool itself appends `git status --short`, `git diff --stat` and the output of the task's `verify` command, so Claude judges by what changed on disk, not by the implementer's report.
+- `/orquestrar` shows the state; `/orquestrar off` turns it off; `/orquestrar modelo <profile>` picks another implementer profile (also `BRITO_IMPL_MODEL` or `implModel` in the config). They combine: `/orquestrar on modelo qwen`. With `--global`, what you asked for is saved in the config: `/orquestrar on --global` turns the mode on every time Brito starts (`orchestrator: true`), and `/orquestrar off --global` undoes it. The status bar shows `⚙ →qwen` while it is on. In the desktop app, use the "Implementa" picker.
+- It only turns on with a valid profile, its key in the environment and a main model other than the implementer. If the main model becomes Qwen (fallback or `/model qwen`), the mode turns off with a warning.
+
 ## Configuration
 
 `BRITO_MODEL`, `BRITO_EFFORT`, `BRITO_EXPLORE_MODEL`, `BRITO_LEARN_MODEL`, `BRITO_HOME` (where global skills and history live), `BRITO_CONFIG`, `BRITO_COLOR`, `BRITO_BANNER` (`compact` or `full`; default: full screen on windows of 95+ columns and 28+ rows), `BRITO_INDEX_IGNORED`, `BRITO_SKILL_MIN_TOOLS` (how long a turn must be to trigger reflection when nothing else does), `BRITO_SKILLS` (`auto` default, `ask`, `off`), `BRITO_SHELL` (shell used by the `bash` tool; on Windows defaults to Git Bash when installed).
@@ -229,7 +279,7 @@ Project data lives in `.brito/` (graph, project skills, agents) and global data
 ## Limitations
 
 - Early software (v0.5.0), one maintainer.
-- The desktop app is new: a single window (no tabs yet), and with an API key (no `claude` CLI) the model does not resume a conversation after you reopen the app, although the screen shows it.
+- The desktop app is young: a single window (no tabs yet), and no image attachments (drop files to reference them with `@path`). API-mode conversations from before this version are not resumed when you reopen the app (new ones are, from `.brito/sessions`).
 - **The interface and the agent's default language are Brazilian Portuguese.** Translating them is a welcome contribution.
 - Skill learning is a heuristic: it proposes, you decide. Expect some proposals to be rejected.
 

package/README.pt-BR.md

@@ -18,7 +18,7 @@ O Brito é um agente para desenvolvimento de software. Use no terminal (`brito-c
 - **Cobertura ampla.** TypeScript/JavaScript, Python e os blocos de script de componentes `.svelte`, `.vue` e `.astro`. Aliases de import (`paths` do tsconfig, `imports` do package.json, `$lib` do SvelteKit) viram arestas de verdade. O que o `.gitignore` ignora fica de fora.
 - **Skills que aprendem sozinhas, em período de teste.** Depois de uma tarefa em que algo tropeçou ou foi corrigido, o Brito reflete e cria uma skill *em teste* sem te interromper. A skill se prova pelo uso: 3 usos limpos a promovem, 2 tropeços a arquivam (recuperável). O que é arriscado, ou qualquer mudança numa skill que você aprovou, continua esperando o seu `/skills approve`. `BRITO_SKILLS=ask` volta a pedir aprovação para tudo; `off` desliga o aprendizado.
 - **Proteções sobre o que é aprendido.** Um lint rejeita segredos, credenciais embutidas em URL, `curl | sh` e frases de injeção de prompt, e **avisa sobre comandos destrutivos** (veja abaixo).
-- **Modos de permissão.** manual, auto-edições, plano e "tudo liberado" (`Shift+Tab` alterna). As skills autônomas não dependem do modo: nascem em teste e são julgadas pelo resultado.
+- **Modos e regras de permissão.** manual, auto-edições, plano e "tudo liberado" (`Shift+Tab` alterna), mais regras `allow`/`deny` por comando ou caminho (veja [Regras de permissão](#regras-de-permissão)). Editar um arquivo exige tê-lo lido na sessão, sem mudanças desde então. As skills autônomas não dependem do modo: nascem em teste e são julgadas pelo resultado.
 - **Dois backends, uma interface.** Use uma chave da API da Anthropic ou a sua assinatura do Claude Code pela CLI `claude`. O Brito nunca lê nem envia o token da sua assinatura.
 - **Terminal ou app de desktop.** `npm i -g brito-cli` instala o comando `brito`; o app de desktop é um executável nativo com janela (projetos e sessões numa barra lateral, chat, pedidos de permissão), sem precisar de Node nem de terminal. Veja [Instalação](#instalação).
 - **Imagens.** Arraste um arquivo de imagem para o prompt (ou cole o caminho) e ele é anexado ao turno: PNG, JPEG, GIF ou WebP, até 5 MB.
@@ -69,6 +69,17 @@ flowchart LR
 
 O lint **rejeita** segredos/tokens, caminhos absolutos do usuário, credenciais em URL (`usuario:senha@host`), `curl | sh` e instruções para sobrepor regras ou pular aprovação. Ele **avisa** (sem bloquear) sobre comandos que destroem dados: apagar arquivos de banco ou de dados, `DROP`/`TRUNCATE`, `DELETE` sem `WHERE`, reset de migrações, `git reset --hard`, force push, remoção de volumes do Docker. Uma skill é uma instrução permanente, então um passo que só era seguro no estado de um momento não pode virar o padrão em silêncio.
 
+## Modelo local (opcional)
+
+`brito slm pull` baixa um modelo local pequeno (Qwen3-4B-Instruct-2507 Q4_K_M, Apache-2.0) para `~/.brito/models`, pela dependência opcional `node-llama-cpp`. `brito slm` mostra o status e `brito slm rm` o apaga. Depois de baixado, ele é usado em:
+
+- **Aprendizado de skills**: a reflexão roda localmente com JSON restrito por gramática e cai no modelo de sempre se algo falhar.
+- **Tool `digest`**: batedor e refinador de textos longos. O modelo local escolhe os blocos mais ligados ao seu objetivo e propõe trechos; o código confere cada citação contra a fonte e descarta o que não existe, e o modelo principal recebe um rascunho pequeno em markdown com citações verificadas e números de página.
+
+- **Fallback quando o Claude acaba**: cadeia Claude → perfil `qwen` → SLM local, com o loop completo do agente e as tools (mesmas permissões). É temporário: passada a janela (o horário de reset que o erro informa, senão 10 min, ou 60 min para cota/auth; `BRITO_FALLBACK_MINUTES` sobrepõe) o próximo turno tenta o Claude de novo. O `/fallback` mostra quando. Um modelo de 4B erra mais com tools: use para continuar, não para tarefas grandes. `BRITO_SLM_FALLBACK=off` tira o SLM da cadeia; `BRITO_SLM_CTX` define o contexto.
+
+`BRITO_SLM=off` desliga; `BRITO_SLM_MODEL` aponta para outro GGUF (URI `hf:` ou caminho de arquivo).
+
 ## Instalação
 
 ### Terminal (`brito-cli`)
@@ -99,7 +110,9 @@ export ANTHROPIC_API_KEY=sk-ant-...      # API da Anthropic
 
 ### App de desktop (executável)
 
-O mesmo agente numa janela: projetos e sessões numa barra lateral, chat com markdown, chamadas de ferramenta recolhíveis, pedidos de permissão e seletores de modelo, esforço e modo de permissão. Não precisa de Node nem de terminal.
+O mesmo agente numa janela: projetos e sessões numa barra lateral, chat com streaming, markdown e copiar código, cartões de ferramenta com diff nas edições, lista de tarefas fixa, pedidos de permissão com diff ("permitir uma vez / nesta sessão / sempre neste projeto") e seletores de modelo, esforço e modo de permissão. Não exige Node nem terminal (no Windows o grafo de código ainda precisa do Node.js 20+).
+
+Além do chat: `/` abre comandos e skills, `@` escolhe arquivos do projeto (ou arraste arquivos para o campo), `Ctrl/Cmd+K` abre a paleta (ações e busca em todas as sessões), há painéis de Skills, Agentes, Grafo de código, Memória e Arquivos alterados, selo do motor (nuvem / endpoint / local) com aviso de fallback, tema claro/escuro e exportação em markdown.
 
 ![App de desktop do Brito respondendo uma pergunta com o grafo de código](docs/images/desktop-app.png)
 
@@ -126,6 +139,9 @@ cd seu-projeto
 brito                       # abre o REPL
 brito "quem chama parseConfig?"   # prompt único, sem REPL
 brito index                 # (re)indexa o grafo; ele também se mantém atualizado sozinho
+brito -c                    # retoma a sessão mais recente deste projeto
+brito sessoes               # lista as sessões salvas; retome uma com brito --resume <id>
+brito slm pull              # (opcional) baixa o modelo local usado por digest e pelo aprendizado de skills
 brito query "MATCH (c:Symbol {kind:'component'})-[:CALLS]->(f:Symbol) RETURN c.file, f.name LIMIT 5"
 ```
 
@@ -146,10 +162,15 @@ OK: 20 arquivos, 66 símbolos, 54 chamadas, 17 imports | +0 ~0 -0 =20 (28ms)
 | `/fallback` | mostra o modelo principal e o fallback (qwen), e se a troca já aconteceu |
 | `/modo` ou `Shift+Tab` | troca o modo de permissão: manual → auto-edições → plano → tudo liberado |
 | `/skills` | lista skills · `pending` · `approve <nome>` · `reject <nome>` · `consolidate` · `rm <nome>` · `promote <nome>` |
+| `/permissions` | lista as regras de permissão · `allow <regra>` · `deny <regra>` |
 | `/learn` | extrai skills do último turno agora |
+| `/grill-me`, `/grill-with-docs`, `/wayfinder`, `/grill-diff` | skills manuais embutidas: entrevista até a ideia ficar firme (`--um` = uma pergunta por mensagem), também grava decisões com `remember`, mapeia trabalho grande e delega, questiona o diff atual |
+| `/skills suggest <tarefa>` | ranqueia as skills (embutidas inclusive) por relevância para a tarefa |
 | `/agents`, `/tools`, `/index`, `/context` | inspecionam subagentes, tools, o índice e a janela de contexto |
 | `!comando` | roda um comando no shell direto, sem chamar o modelo |
-| `/clear`, `/exit` | limpa a conversa, sai |
+| `/todos` | mostra a lista de tarefas da sessão (o agente a mantém com `todo_write` em tarefas de vários passos) |
+| `/sessions` | lista as sessões salvas deste projeto |
+| `/clear`, `/exit` | começa outra conversa (a anterior continua salva), sai |
 
 ## O que o grafo indexa
 
@@ -159,6 +180,26 @@ OK: 20 arquivos, 66 símbolos, 54 chamadas, 17 imports | +0 ~0 -0 =20 (28ms)
 - **Linguagens de backend:** o grafo guarda classes/interfaces/structs/traits/enums/módulos, funções e métodos (`Classe.metodo`), chamadas e imports. Nelas o import nomeia um pacote, não um caminho; o Brito casa o especificador com o final do caminho dos seus arquivos (`com.acme.Repo` ↔ `src/main/java/com/acme/Repo.java`; namespaces PSR-4 do PHP; `use crate::…` do Rust; `require`/`require_relative` do Ruby; pacotes Go pelo módulo do `go.mod`). Pacote externo (`java.util`, `serde`, `github.com/gin-gonic/gin`) nunca casa e não gera aresta. Não há inferência de tipos: `userRepository.save()` é ligado casando o nome do receptor com um tipo do projeto (`UserRepository`), `this`/`self`/receiver resolvem para a classe que contém a chamada, e uma chamada solta dentro de classe tenta primeiro os métodos da própria classe.
 - **Ainda não:** `extends` por pacote (`@tsconfig/node20`), `exports` de workspaces vizinhos e referências de função sem chamada em um template (`onclick={fn}`). As chamadas são resolvidas estaticamente, com fallback por nome, então despacho dinâmico e reflexão não são capturados.
 
+## Regras de permissão
+
+Para não aprovar o mesmo comando toda vez (nem precisar do "tudo liberado"), declare regras em `.brito/settings.json` (do projeto, pode ir para o git), `.brito/settings.local.json` (só seu) ou `~/.brito/settings.json` (todos os projetos). As listas se somam.
+
+```json
+{
+  "permissions": {
+    "allow": ["bash(npm test:*)", "bash(npm run typecheck)", "bash(git status:*)", "edit_file(src/**)"],
+    "deny": ["bash(git push:*)", "bash(rm -rf*)", "read_file(.env*)"]
+  }
+}
+```
+
+- `tool` vale para qualquer uso; `tool(padrão)` restringe. Em `bash`, `*` casa qualquer coisa e `:*` no fim casa o prefixo sozinho ou com argumentos (`git status:*` libera `git status --short`, não `git statusx`). Em caminhos, `*` não cruza diretórios e `**` cruza.
+- **`allow` dispensa a pergunta** nos modos manual e auto-edições. O modo plano continua bloqueando.
+- **`deny` bloqueia sempre**, inclusive no "tudo liberado".
+- Um comando composto só é liberado se **cada pedaço** (`&&`, `||`, `;`, `|`) casar com uma regra: `bash(npm test*)` não libera `npm test && rm -rf ~`. Comandos com `$(...)`, crases ou redirecionamento para arquivo nunca são liberados por regra; `2>&1` e `> /dev/null` podem.
+- As regras valem também para o Bash, o Edit e o Write do `claude` CLI quando o Brito roda sobre a sua assinatura.
+- `/permissions` lista as regras; `/permissions allow bash(npm test:*)` grava no `.brito/settings.json`.
+
 ## Bancos de dados e outros recursos sensíveis
 
 O Brito **não tem drivers de banco e não se conecta a nada sozinho**. Quando precisa mexer em um banco, usa as ferramentas do próprio projeto pelo shell, sob o modo de permissão que você escolheu. Como cada projeto é diferente (um arquivo local, um servidor remoto, um container), declare as partes sensíveis no `BRITO.md` (ou `CLAUDE.md` / `AGENTS.md`), que é lido para o system prompt:
@@ -223,6 +264,15 @@ Com o Claude como modelo principal (API ou `claude` CLI), o perfil `qwen` é o f
   estado     inativo — troca automática se o Claude falhar por limite, crédito, auth ou sobrecarga
 ```
 
+### Modo orquestrador: o Claude planeja, o Qwen implementa
+
+`/orquestrar on` mantém o Claude como modelo principal, mas passa a implementação para um perfil de endpoint (`qwen` por padrão). O Claude grava a spec e a lista de tasks em `spec/<feature>/spec.md` e `spec/<feature>/tasks.md` (tool `spec_save`), espera sua aprovação e só então manda uma task por vez para a tool `implement`, marcando no `tasks.md` as que passaram na revisão. Ele perde as tools de edição (`write_file`/`edit_file`, ou `Edit`/`Write`/`MultiEdit`/`NotebookEdit` no modo `claude` CLI): a única escrita dele é a `spec_save`, que só grava esses dois arquivos. Fica com a leitura, o grafo e o `bash` para conferir o trabalho.
+
+- O implementador roda em contexto isolado (não vê a conversa), com o grafo dos símbolos passados em `focus`. As edições e comandos dele seguem o modo de permissão e, no modo `claude` CLI, são aprovados no terminal como os do Claude.
+- Quando ele termina, a própria tool anexa `git status --short`, `git diff --stat` e a saída do comando `verify` da task: o Claude julga pelo que mudou no disco, não pelo relato do implementador.
+- `/orquestrar` mostra o estado; `/orquestrar off` desliga; `/orquestrar modelo <perfil>` escolhe outro perfil implementador (também `BRITO_IMPL_MODEL` ou `implModel` no config). Os dois combinam: `/orquestrar on modelo qwen`. Com `--global`, o que foi pedido fica salvo no config: `/orquestrar on --global` liga o modo sempre que o Brito abrir (`orchestrator: true`), e `/orquestrar off --global` desfaz. A barra de status mostra `⚙ →qwen` enquanto o modo está ligado. No app de desktop, use o seletor "Implementa".
+- Só liga com o perfil válido, a chave no ambiente e um modelo principal diferente do implementador. Se o principal virar o Qwen (fallback ou `/model qwen`), o modo desliga com aviso.
+
 ## Configuração
 
 `BRITO_MODEL`, `BRITO_EFFORT`, `BRITO_EXPLORE_MODEL`, `BRITO_LEARN_MODEL`, `BRITO_HOME` (onde ficam skills globais e histórico), `BRITO_CONFIG`, `BRITO_COLOR`, `BRITO_BANNER` (`compact` ou `full`; padrão: tela cheia em janelas de 95+ colunas e 28+ linhas), `BRITO_INDEX_IGNORED`, `BRITO_SKILL_MIN_TOOLS` (tamanho mínimo do turno para disparar a reflexão quando nada mais dispara), `BRITO_SKILLS` (`auto` padrão, `ask`, `off`), `BRITO_SHELL` (shell da tool `bash`; no Windows usa o Git Bash se instalado).
@@ -232,7 +282,7 @@ Os dados do projeto ficam em `.brito/` (grafo, skills do projeto, agentes) e os
 ## Limitações
 
 - Software em fase inicial (v0.5.0), um mantenedor.
-- O app de desktop é novo: uma janela só (sem abas ainda) e, com chave de API (sem o `claude` CLI), o modelo não retoma a conversa ao reabrir o app, embora a tela a mostre.
+- O app de desktop é jovem: uma janela só (sem abas ainda) e sem anexo de imagem (arraste arquivos para referenciá-los com `@caminho`). Conversas do modo API feitas antes desta versão não são retomadas ao reabrir o app (as novas são, a partir de `.brito/sessions`).
 - **A interface e o idioma padrão do agente são português do Brasil.** Traduzi-los é uma contribuição bem-vinda.
 - O aprendizado de skills é heurístico: ele propõe, você decide. Espere rejeitar algumas propostas.
 

package/dist/agent/approval.js

@@ -3,11 +3,22 @@ import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { describeClaudeTool, perms } from "../permissions.js";
+import { decide, loadRules } from "../rules.js";
 /**
  * Aprovações do claude CLI: o claude chama a tool MCP `approve` (--permission-prompt-tool), que roda no
  * processo do servidor MCP e consulta ESTE processo por um socket unix, onde está o terminal (ou a janela do app).
  */
-export function startApprovalServer(io) {
+/** Traduz uma tool do claude CLI para o nome e o input das tools do Brito e decide pelas regras de permissão. */
+export function claudeDecision(root, tool, input) {
+    const file = typeof input?.file_path === "string" ? input.file_path : undefined;
+    const mapped = tool === "Bash" ? { name: "bash", input: { command: input?.command } } :
+        (tool === "Edit" || tool === "MultiEdit") && file ? { name: "edit_file", input: { path: file } } :
+            tool === "Write" && file ? { name: "write_file", input: { path: file } } :
+                { name: tool, input };
+    return decide(loadRules(root), mapped.name, mapped.input, root);
+}
+/** `root` liga as regras de permissão do projeto; sem ele, toda chamada é perguntada como antes. */
+export function startApprovalServer(io, root) {
     // No Windows um socket unix em %TEMP% não é aceito por net.listen: o endereço tem que ser um named pipe.
     const sock = process.platform === "win32" ? `\\\\.\\pipe\\brito-approve-${process.pid}` : path.join(os.tmpdir(), `brito-approve-${process.pid}.sock`);
     try {
@@ -25,7 +36,13 @@ export function startApprovalServer(io) {
             try {
                 const req = JSON.parse(buf.slice(0, nl));
                 const plan = req.tool_name === "ExitPlanMode";
-                const ok = await io.ask(describeClaudeTool(req.tool_name, req.input), { force: plan });
+                // As regras do Brito valem também para as tools do claude: deny bloqueia, allow dispensa a pergunta.
+                const decision = root && !plan ? claudeDecision(root, req.tool_name, req.input) : "ask";
+                if (decision === "deny") {
+                    conn.end(JSON.stringify({ allow: false, message: "Bloqueado por uma regra deny das permissões do Brito (.brito/settings.json). Não tente contornar." }) + "\n");
+                    return;
+                }
+                const ok = decision === "allow" || await io.ask(describeClaudeTool(req.tool_name, req.input), { force: plan });
                 if (ok && plan)
                     perms.mode = "manual";
                 reply = ok ? { allow: true } : { allow: false, message: plan ? "Plano não aprovado pelo usuário. Pergunte o que ajustar." : "O usuário negou a execução." };

package/dist/agent/claude-cli.js

@@ -7,6 +7,7 @@ import { skillsIndex } from "../skills/store.js";
 import { MCP_NAME, MCP_PREFIX, APPROVE_TOOL } from "../mcp/server.js";
 import { ui as terminalUi } from "../ui/ui.js";
 import { MODE_ENV, perms } from "../permissions.js";
+import { CLAUDE_EDIT_TOOLS, ORCH_MCP_TIMEOUT, ORCH_NOTE, ORCH_NOTE_CLAUDE, orch, orchEnv } from "../orchestrator.js";
 import { DEFAULT_MODEL, wireEffort } from "../model.js";
 import { subagentModel } from "../engine.js";
 import { claudeCommand } from "../util/platform.js";
@@ -211,11 +212,13 @@ export class ClaudeSession {
     aborted = false;
     args(text, imageDirs = []) {
         const { root, approvalSock, stats, mcpCommand } = this.o;
-        const mcp = mcpConfig(mcpCommand, approvalSock, perms.mode, this.o.env);
-        const readOnlyMcp = ["graph_search", "graph_callers", "graph_callees", "graph_impact", "graph_context", "graph_query", "graph_index", "remember", "recall", "skill_load"];
+        // O modo orquestrador vale por turno, como o de permissão: o servidor MCP do turno sobe com ele no env.
+        const mcp = mcpConfig(mcpCommand, approvalSock, perms.mode, { ...this.o.env, ...orchEnv() });
+        const readOnlyMcp = ["graph_search", "graph_callers", "graph_callees", "graph_impact", "graph_context", "graph_query", "graph_index", "remember", "recall", "skill_load", "digest"];
         const system = buildSystemPrompt(root, stats, skillsIndex(root)) +
             `\n\n# Nesta sessão\nAs tools do Brito chegam com o prefixo \`${MCP_PREFIX}\` (ex.: ${MCP_PREFIX}graph_context). Use-as como descrito acima. ` +
-            `read_file/grep/glob/edit_file/bash correspondem a Read/Grep/Glob/Edit/Bash, e \`delegate\` corresponde à tool Agent/Task com os subagentes configurados (explore, plan, general e os do projeto).`;
+            `read_file/grep/glob/edit_file/bash correspondem a Read/Grep/Glob/Edit/Bash, e \`delegate\` corresponde à tool Agent/Task com os subagentes configurados (explore, plan, general e os do projeto).` +
+            (orch.on ? ORCH_NOTE + ORCH_NOTE_CLAUDE : "");
         const args = [
             "-p", text,
             this.started ? "--resume" : "--session-id", this.id,
@@ -234,6 +237,8 @@ export class ClaudeSession {
         // O modo vale por turno: Shift+Tab no REPL muda o próximo turno.
         const mode = { manual: "default", auto: "acceptEdits", plan: "plan", bypass: "bypassPermissions" }[perms.mode];
         args.push("--permission-mode", mode);
+        if (orch.on)
+            args.push("--disallowedTools", ...CLAUDE_EDIT_TOOLS);
         if (perms.mode !== "bypass") {
             args.push("--allowedTools", ...readOnlyMcp.map((n) => MCP_PREFIX + n), "--permission-prompt-tool", `${MCP_PREFIX}${APPROVE_TOOL}`);
         }
@@ -255,7 +260,8 @@ export class ClaudeSession {
             const child = (this.child = spawn(cmd.command, cmd.args, {
                 cwd: this.o.root, stdio: ["ignore", "pipe", "pipe"],
                 // `/reasoning none`: o claude desliga o raciocínio com MAX_THINKING_TOKENS=0 (não há `--effort none`)
-                env: { ...process.env, ...this.o.env, BRITO_DEPTH: String(Number(process.env.BRITO_DEPTH ?? 0) + 1), ...(wireEffort(this.effort).thinking ? {} : { MAX_THINKING_TOKENS: "0" }) },
+                env: { ...process.env, ...this.o.env, BRITO_DEPTH: String(Number(process.env.BRITO_DEPTH ?? 0) + 1),
+                    ...(orch.on && !process.env.MCP_TOOL_TIMEOUT ? { MCP_TOOL_TIMEOUT: ORCH_MCP_TIMEOUT } : {}), ...(wireEffort(this.effort).thinking ? {} : { MAX_THINKING_TOKENS: "0" }) },
             }));
             let buf = "", stderr = "", ok = true, interrupted = false;
             const failure = { stderr: "", code: null };

package/dist/agent/loop.js

@@ -5,8 +5,9 @@ import { initialEffort, initialModel } from "../model.js";
 import { providerFor } from "../provider/index.js";
 import { compactAtFor, resolveModel } from "../provider/resolve.js";
 import { fallbackStatus } from "../engine.js";
-import { activateFallback, classifyAnthropicError, fallbackWarning, shortError, triggersFallback } from "../provider/fallback.js";
+import { activateFallback, classifyAnthropicError, fallbackExpired, fallbackUntil, fallbackWarning, returnToPrimary, shortError, triggersFallback } from "../provider/fallback.js";
 import { fmtBytes, findImages, imageBlock, splitOversize } from "../util/images.js";
+import { orchGuard } from "../orchestrator.js";
 export const MODEL = initialModel();
 export class Agent {
     system;
@@ -80,6 +81,7 @@ export class Agent {
         }
         else
             push({ role: "user", content: userText });
+        this.retryPrimaryIfExpired();
         await this.compactIfNeeded();
         let finalText = "";
         for (let step = 0; step < this.maxSteps; step++) {
@@ -116,7 +118,8 @@ export class Agent {
                 const t0 = Date.now();
                 if (!this.opts.quiet)
                     this.ui.toolStart(u.id, u.name, u.input);
-                const denied = this.opts.tools && !this.opts.tools.has(u.name);
+                const allow = this.allowed();
+                const denied = allow && !allow.has(u.name);
                 const r = denied ? { text: `Tool não permitida para este agente: ${u.name}`, isError: true } : await execTool(u.name, u.input, this.ctx);
                 if (this.opts.quiet)
                     this.log(terminalUi.toolLine(u.name, u.input, Date.now() - t0, r.isError));
@@ -147,31 +150,57 @@ export class Agent {
         try {
             return await providerFor(this.model).send({
                 model: this.model,
-                maxTokens: target.kind === "openai" && thinking ? 16_384 : 8192,
+                // Na Anthropic a resposta vem por streaming, então o teto pode ser alto sem risco de timeout: um
+                // write_file grande não é mais cortado no meio.
+                maxTokens: target.kind === "openai" ? (thinking ? 16_384 : 8192) : 32_000,
                 system: typeof this.system === "function" ? this.system() : this.system,
-                tools: toApiTools(this.opts.tools),
+                tools: toApiTools(this.allowed()),
                 messages: this.messages,
                 thinking,
+                effort: this.effort,
             }, hooks);
         }
         catch (e) {
             const fb = this.opts.fallback;
-            if (!fb || fb.active || hooks.signal?.aborted || target.kind !== "anthropic")
+            if (!fb || hooks.signal?.aborted)
                 throw e;
-            const kind = classifyAnthropicError(e);
+            // Claude → qwen → SLM: com o fallback ativo só desce um degrau (qwen que falha cai no SLM), nunca o SLM.
+            const onQwen = fb.active && target.kind === "openai" && !target.local && target.name === "qwen";
+            if (fb.active ? !onQwen : target.kind !== "anthropic" || target.local)
+                throw e;
+            if (onQwen && target.kind !== "openai")
+                throw e;
+            const kind = onQwen ? "network" : classifyAnthropicError(e);
             if (!triggersFallback(kind))
                 throw e;
-            const status = fallbackStatus(this.model, process.env);
+            const status = fallbackStatus(fb.primary, process.env, onQwen ? ["qwen"] : []);
             if (!status.ready)
                 throw e;
             const why = shortError(e);
-            this.ui.warn(fallbackWarning(kind, why, status.label));
-            activateFallback(fb, `${kind} (${why})`);
+            const until = onQwen ? fb.until : fallbackUntil(kind, why);
+            this.ui.warn(fallbackWarning(kind, why, status.label, until));
+            activateFallback(fb, `${kind} (${why})`, Date.now(), until, status.name);
             this.model = status.name;
+            orchGuard(this.model, (m) => this.ui.warn(m)); // o qwen virou o principal: não há mais a quem delegar
             await this.compactIfNeeded();
             return this.callModel(hooks);
         }
     }
+    allowed() {
+        return typeof this.opts.tools === "function" ? this.opts.tools() : this.opts.tools;
+    }
+    /**
+     * Fallback temporário: passada a janela, o próximo turno tenta o Claude de novo (se falhar, `callModel` reativa o
+     * fallback com uma janela nova). Só com ANTHROPIC_API_KEY: sem ela o Claude não roda neste loop (volta via /model).
+     */
+    retryPrimaryIfExpired() {
+        const fb = this.opts.fallback;
+        if (!fb || !fallbackExpired(fb) || !process.env.ANTHROPIC_API_KEY?.trim() || resolveModel(fb.primary).kind !== "anthropic")
+            return;
+        returnToPrimary(fb);
+        this.model = fb.primary;
+        this.ui.info(`voltando ao Claude (${fb.primary}) para testar se o limite acabou`);
+    }
     async compactIfNeeded() {
         if (estimateTokens(this.messages) < compactAtFor(this.model))
             return;

package/dist/agent/prompt.js

@@ -34,13 +34,39 @@ export function buildSystemPrompt(root, graphStats, skills = "") {
 - Edições e comandos shell pedem aprovação do usuário. Prefira edit_file a write_file. Verifique seu trabalho (typecheck/testes) via bash quando existir.
 - Para investigações amplas ou sub-tarefas grandes, use delegate: o subagente trabalha em contexto isolado e devolve só o resultado. Vários delegate somente-leitura (explore/plan) no mesmo turno rodam em paralelo. Passe \`focus\` com os símbolos relevantes. Não delegue o que resolve com 1–2 chamadas de graph_*.
 - SKILLS: procedimentos reutilizáveis aprendidos neste projeto. Se alguma se aplica à tarefa, chame skill_load ANTES de começar e siga-a. Se ela estiver errada ou incompleta, corrija com skill_save. Ao terminar tarefas complexas, o sistema pode propor novas skills; não crie skill para fatos de uma tarefa única.
+- Em tarefas com 3+ passos, mantenha a lista com todo_write: um item in_progress por vez, marcado completed assim que terminar. Leia um arquivo (read_file) antes de editá-lo; se ele mudou desde a leitura, leia de novo.
 - Seja conciso. Não repita conteúdo de arquivos na resposta.
 
 # Ambiente
 Diretório do projeto: ${root}
 Data: ${new Date().toISOString().slice(0, 10)}${shellNote()}${skills ? `\n\n# Skills disponíveis (use skill_load)\n${skills}` : ""}${projectDoc}`;
 }
-import { skillsIndex } from "../skills/store.js";
+import { listSkills, skillsIndex } from "../skills/store.js";
+/**
+ * Repete o system prompt anterior enquanto `key()` não muda. O cache de prompt da API é um prefixo: qualquer byte
+ * diferente no system (a contagem de símbolos após um sync, a ordem das skills por uso) invalidaria o cache da
+ * conversa inteira a cada passo. A chave lista só o que muda o que o modelo deve fazer.
+ */
+export function memoSystem(key, build) {
+    let last;
+    let value = "";
+    return () => {
+        const k = key();
+        if (k !== last) {
+            last = k;
+            value = build();
+        }
+        return value;
+    };
+}
+/**
+ * Chave do `memoSystem` da sessão principal: modo plano, grafo vazio ou não (o aviso de "grafo vazio" muda a
+ * orientação) e o conjunto de skills com o status. Contagens e ordem por uso ficam de fora de propósito.
+ */
+export function systemKey(root, planMode, graphEmpty) {
+    const skills = listSkills(root).map((s) => `${s.name}:${s.scope}:${s.status}`).sort().join(",");
+    return `${planMode}|${graphEmpty}|${skills}`;
+}
 export function buildSubagentPrompt(root, def) {
     return `${def.prompt}
 

package/dist/agent/sessions.js

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import path from "node:path";
+const MAX_SESSIONS = 50;
+const ID = /^[\w-]{1,80}$/;
+export const sessionsDir = (root) => path.join(root, ".brito", "sessions");
+const fileOf = (root, id) => {
+    if (!ID.test(id))
+        throw new Error(`id de sessão inválido: ${id}`);
+    return path.join(sessionsDir(root), `${id}.json`);
+};
+const stripImages = (msgs) => msgs.map((m) => typeof m.content === "string" ? m : {
+    ...m,
+    content: m.content.map((b) => (b.type === "image" || b.type === "document" ? { type: "text", text: "[anexo omitido ao salvar a sessão]" } : b)),
+});
+export function titleOf(msgs, fallback = "") {
+    const first = msgs?.find((m) => m.role === "user");
+    const text = typeof first?.content === "string" ? first.content : first?.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join(" ") ?? fallback;
+    return (text || fallback).replace(/\s+/g, " ").trim().slice(0, 80);
+}
+/** Grava (ou atualiza) a sessão. Nunca derruba o turno: falha de disco vira aviso de quem chamou. */
+export function saveSession(root, s, now = new Date()) {
+    const dir = sessionsDir(root);
+    fs.mkdirSync(dir, { recursive: true });
+    // Conversas são pessoais e podem citar dados sensíveis: nunca vão para o git por acidente.
+    try {
+        fs.writeFileSync(path.join(dir, ".gitignore"), "*\n", { flag: "wx" });
+    }
+    catch (e) {
+        if (e.code !== "EEXIST")
+            throw e;
+    }
+    const prev = loadSession(root, s.id);
+    const out = {
+        v: 1, ...s,
+        ...(s.messages ? { messages: stripImages(s.messages) } : {}),
+        createdAt: s.createdAt ?? prev?.createdAt ?? now.toISOString(),
+        updatedAt: now.toISOString(),
+    };
+    const file = fileOf(root, s.id);
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(out));
+    fs.renameSync(tmp, file); // atômico: um Ctrl+C no meio não deixa JSON cortado
+    prune(root);
+}
+export function loadSession(root, id) {
+    try {
+        const s = JSON.parse(fs.readFileSync(fileOf(root, id), "utf8"));
+        return s?.v === 1 && typeof s.id === "string" ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Mais recentes primeiro. */
+export function listSessions(root) {
+    let names;
+    try {
+        names = fs.readdirSync(sessionsDir(root)).filter((n) => n.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+    return names
+        .flatMap((n) => { const s = loadSession(root, n.slice(0, -5)); return s ? [s] : []; })
+        .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+export const latestSession = (root, engine) => listSessions(root).find((s) => !engine || s.engine === engine) ?? null;
+/** Mantém as `MAX_SESSIONS` mais recentes, pela data do arquivo (sem abrir históricos que podem ter megabytes). */
+function prune(root) {
+    const dir = sessionsDir(root);
+    const files = fs.readdirSync(dir).filter((n) => n.endsWith(".json")).map((n) => {
+        try {
+            return { n, t: fs.statSync(path.join(dir, n)).mtimeMs };
+        }
+        catch {
+            return { n, t: 0 };
+        }
+    }).sort((a, b) => b.t - a.t);
+    for (const f of files.slice(MAX_SESSIONS)) {
+        try {
+            fs.unlinkSync(path.join(dir, f.n));
+        }
+        catch { /* já removida */ }
+    }
+}
+/**
+ * Histórico salvo pronto para reenviar: se o processo caiu no meio de um turno, o último `tool_use` pode ter ficado sem
+ * `tool_result`, e a API recusaria a conversa. Fecha cada um com erro, como no Ctrl+C.
+ */
+export function repairHistory(msgs) {
+    const last = msgs[msgs.length - 1];
+    if (last?.role !== "assistant" || typeof last.content === "string")
+        return msgs;
+    const pending = last.content.filter((b) => b.type === "tool_use");
+    if (!pending.length)
+        return msgs;
+    return [...msgs, { role: "user", content: pending.map((u) => ({ type: "tool_result", tool_use_id: u.id, content: "Sessão interrompida antes desta tool terminar.", is_error: true })) }];
+}