kafox-cli 0.3.0 → 0.7.0

package/README.md

@@ -23,44 +23,163 @@ Requisito: Node.js 22.5+.
 kafox login
 ```
 
-A CLI mostra um codigo e a URL `https://kafox.pypag.com/cli?code=...`. Abra no
-navegador, entre na sua conta e clique em **Autorizar**. A sessao fica em
-`~/.kafox/token.json` (permissao 600).
+O terminal vira uma tela de login (arte grande em cima, link no centro): abra a
+URL `https://kafox.pypag.com/cli?code=...`, entre na sua conta e clique em
+**Autorizar**. A sessao fica em `~/.kafox/token.json` (permissao 600). No primeiro
+`kafox` sem sessao ele pergunta se quer entrar e abre a mesma tela.
 
 ## Comandos
 
 | Comando | O que faz |
 | --- | --- |
 | `kafox` | abre a interface de tela cheia |
+| `kafox --allow-all` | abre ja aprovando tudo (mesmo que `KAFOX_ALLOW_ALL=1`) |
 | `kafox login` / `logout` / `whoami` | sessao da conta |
 | `kafox models` | lista modelos e precos por 1M de tokens |
 | `kafox pricing` | pacotes de recarga |
 | `kafox balance` | saldo atual |
 | `kafox key` | cria uma API key |
 | `kafox ask "pergunta" [-m modelo]` | pergunta ao gateway |
+| `kafox agent "objetivo" [-y] [--max-steps 12] [--json]` | roda o agente sem TUI (script/CI) |
+| `kafox history` | lista as conversas salvas (titulo + como retomar) |
+| `kafox resume [codigo]` | retoma uma conversa; sem codigo abre o seletor na tela |
+| `kafox continue` / `kafox -c` | volta para a conversa mais recente |
 | `kafox status` | conta, saldo e gateway |
 | `kafox theme` | seletor de tema |
 | `kafox background [url]` | imagem de fundo do terminal |
 | `kafox compact` / `clear` | compacta / limpa o contexto do REPL |
 
+## Conversas salvas
+
+Toda conversa fica em `~/.kafox/chats/<codigo>.json`. Ao sair com **Ctrl+C** a
+CLI mostra o codigo:
+
+```
+  Retome esta conversa: kafox --resume 3f1c9a0b
+```
+
+`kafox history` lista tudo:
+
+```
+- hello world em python solicitado, usa arquivo e roda teste
+  kafox resume 3f1c9a0b
+```
+
+`kafox resume` (sem codigo) abre o seletor com os titulos das conversas — setas
+ou mouse escolhem, Enter retoma. `kafox continue` (ou `-c`) vai direto para a
+ultima.
+
+## Agentes e subagentes
+
+O agente tem a ferramenta `spawn_subagent`: ele lança subagentes com objetivo
+próprio, cada um num contexto separado, e recebe só o relatório final. Vão até
+3 tarefas por chamada e as independentes rodam em paralelo. Por padrão o
+subagente só lê (`read_file`, `list_dir`); escrever, editar ou executar exige
+declarar a ferramenta na tarefa — e continua passando pela aprovação normal
+(ou pelo `/allow`).
+
+```bash
+kafox agent "revise src/agent.js e aponte bugs" --max-steps 8
+kafox agent "rode os testes do backend e resuma as falhas" -y --json
+```
+
+Para ver o que os subagentes da sessão fizeram (objetivo, ferramentas, tempo e
+se terminaram), use `/agents` — o mesmo comando funciona no REPL e na TUI.
+
 Na interface: digite `/` para o menu (↑/↓ navega, Tab completa, Enter executa),
-`/model` abre o seletor de modelo (↑/↓ + Enter). Respostas sao renderizadas em
-Markdown (titulos, listas, negrito e codigo). PgUp/PgDn ou a roda do mouse rolam a
-conversa. Saidas de comando abrem num modal central; qualquer tecla fecha. Demais comandos: `/help`,
-`/models`, `/balance`, `/pricing`, `/key`, `/login`, `/logout`, `/whoami`,
-`/theme`, `/background`, `/clear`, `/compact`, `/status`, `/exit`.
+`/model` abre o seletor de modelo e `/theme` o de tema (↑/↓, clique do mouse,
+Enter aplica, Esc cancela). A resposta chega em streaming, com bloco `Thinking`
+quando o modelo manda o raciocinio. PgUp/PgDn ou a roda do mouse rolam a conversa;
+Ctrl+Y copia a ultima resposta e F2 solta o mouse para selecionar texto.
+
+Enquanto o modelo trabalha a caixa de texto mostra `trabalhando...` com os
+pontinhos correndo, e o nome do modelo aparece fora dela, na linha de baixo.
+Se a rede cair (`fetch failed`), a CLI tenta de novo sozinha ate 20 vezes
+dobrando a espera (3s, 6s, 12s, 24s... ate 60s) e mostra a contagem na linha do
+modelo; **Esc** cancela a espera na hora. O agente nao tem limite de passos: ele
+continua ate terminar.
+
+Nao precisa esperar a resposta para escrever de novo: **Enter enfileira** a
+mensagem (a fila aparece acima do input e roda em ordem assim que a atual
+termina). Para parar a IA na hora, **Esc duas vezes** — o primeiro Esc so avisa,
+o segundo interrompe o passo em andamento e guarda na conversa o que ja tinha
+chegado.
+
+Demais comandos: `/help`, `/models`, `/balance`, `/pricing`, `/key`, `/login`,
+`/logout`, `/whoami`, `/mcp`, `/allow`, `/theme`, `/background`, `/clear`,
+`/compact`, `/status`, `/exit`.
+
+O `/theme` traz 29 temas (default, dark, light, brutalist, neon, paper,
+dracula, nord, gruvbox, monokai, tokyo-night, catppuccin, solarized, midnight,
+ocean, forest, sunset, plum, synthwave, cyberpunk, amoled, matrix, terminal,
+solarized-light, rose, mint, sepia, ice e high-contrast).
+
+## Ferramentas do agente
+
+Com o saldo em dia a TUI deixa o modelo ler e mexer no projeto. Cada chamada
+aparece como um card na conversa, com o diff do que foi editado.
+
+| Ferramenta | O que faz |
+| --- | --- |
+| `read_file` | le um arquivo (com `offset`/`limit`) |
+| `list_dir` | lista uma pasta |
+| `write_file` | cria ou reescreve um arquivo |
+| `edit_file` | troca um trecho exato do arquivo |
+| `run_command` | roda um comando no diretorio de trabalho |
+
+`run_command` sai como uma janela de terminal: o comando em `$ ...`, a saida
+dentro da janela (erro em vermelho) e o rodape com `exit` e o tempo; enquanto
+roda, aparece o spinner com o tempo decorrido. Ferramentas de MCP usam a mesma
+janela, com os argumentos e o resultado.
+
+Quem escreve, edita ou executa pede aprovacao num modal com tres opcoes:
+**Permitir uma vez**, **Permitir sempre** (roda tudo nesta sessao, sem perguntar
+de novo — inclusive as proximas ferramentas do mesmo passo) e **Negar**. Navegue
+com ↑/↓ (ou clique) e confirme com Enter; `a` libera sempre, `y` uma vez,
+`n`/Esc nega. Todo caminho fica travado dentro do diretorio de trabalho.
+
+Para ja abrir liberado, use `kafox --allow-all` (ou `KAFOX_ALLOW_ALL=1`), e dentro
+da sessao `/allow` liga e `/allow off` volta a perguntar. Com o modo ligado a
+barra lateral mostra **rodando tudo**.
+
+## Servidores MCP
+
+Ferramentas de servidores MCP entram no mesmo loop, com o prefixo
+`mcp__servidor__ferramenta`. Configure em `~/.kafox/mcp.json` (ou `./mcp.json` do
+projeto, que vence):
+
+```json
+{
+  "mcp": {
+    "playwright": {
+      "type": "local",
+      "command": ["npx", "-y", "@playwright/mcp@latest"]
+    },
+    "remoto": {
+      "type": "remote",
+      "url": "https://exemplo.com/mcp",
+      "headers": { "authorization": "Bearer ..." }
+    }
+  }
+}
+```
+
+O servidor local roda por stdio e o remoto fala HTTP/SSE. Use `enabled: false`
+para desligar um servidor. Na TUI a barra lateral mostra o status de cada um (e o
+motivo do erro quando falha) e `/mcp` lista tudo; `/mcp reload` reconecta.
 
 ## Configuracao
 
 - `KAFOX_API_URL` ou `~/.kafox/config.json` (`api_url`) troca a API.
 - `~/.kafox/config.json` guarda `model`, `theme`, `background` e a API key criada
   automaticamente no primeiro `ask`.
+- `~/.kafox/mcp.json` guarda os servidores MCP.
 
 A CLI so responde se a conta tiver saldo; sem credito ela avisa e nao chama o
 gateway.
 
 ## Escopo
 
-O kafox e um cliente de conversa: autentica na conta, lista modelos, mostra saldo
-e envia mensagens ao gateway. Ele nao executa ferramentas locais nem conecta
-servidores MCP.
+O kafox autentica na conta, lista modelos, mostra saldo, conversa pelo gateway e
+roda tarefas no projeto: le e edita arquivos, executa comandos (sempre com
+aprovacao) e chama servidores MCP configurados.

package/bin/kafox.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+const chalk = require("chalk");
 const { Command } = require("commander");
 const { version } = require("../package.json");
 const { runREPL, compact, clearContext, showStatus } = require("../src/cli");
@@ -6,27 +7,97 @@ const { login, logout, whoami, createKey } = require("../src/auth");
 const { listModels, showBalance, showPricing } = require("../src/models");
 const { ask } = require("../src/gateway");
 const { runTheme, setContentBackground } = require("../src/theme");
+const { runHeadless } = require("../src/runner");
 
 const program = new Command();
 
 program
   .name("kafox")
   .description("Kafox CLI in opencode style: terminal UI, account login, models, balance, themes")
+  .option(
+    "-y, --allow-all",
+    "abre ja aprovando tudo: ferramentas de arquivo, comando e MCP sem pedir aprovacao"
+  )
+  .option(
+    "--resume [codigo]",
+    "retoma uma conversa salva (o codigo aparece no Ctrl+C e no `kafox history`)"
+  )
+  .option("-c, --continue", "retoma a conversa mais recente")
   .version(version);
 
+/** `kafox history`: titulo de cada conversa e como retomar. */
+function printHistory() {
+  const sessions = require("../src/sessions");
+  const chats = sessions.list();
+  if (!chats.length) {
+    console.log("Nenhuma conversa salva ainda.");
+    return;
+  }
+  for (const chat of chats) {
+    console.log(`- ${chalk.bold(chat.title)}`);
+    console.log(`  kafox resume ${chat.id}`);
+    console.log("");
+  }
+}
+
 program.command("login").description("Login with your Kafox account (device code SSO)").action(login);
 program.command("logout").description("End the CLI session").action(logout);
 program.command("whoami").description("Show the account linked to this CLI").action(whoami);
-program.command("models").description("List available models and prices").action(listModels);
+program.command("models").description("List available models").action(listModels);
 program.command("balance").description("Show current balance").action(showBalance);
 program.command("pricing").description("Show recharge packages").action(showPricing);
 program.command("key").description("Create an API key for this CLI").action(createKey);
 program.command("ask").argument("[question...]", "Question").option("-m, --model <id>", "Model").action(ask);
+program
+  .command("agent")
+  .description("Run the agent without the TUI (tools, subagents, scripting)")
+  .argument("<objective...>", "Objetivo do agente")
+  .option("-m, --model <id>", "Model")
+  // -y/--allow-all é global (declarado no programa): declarar de novo aqui
+  // fazia o commander esconder a flag e o agente nunca rodava liberado.
+  .option("--max-steps <n>", "limite de passos (padrao: sem limite)", "0")
+  .option("--json", "imprime só o resultado em JSON")
+  .option("-q, --quiet", "esconde o progresso das ferramentas")
+  .action(async (objective, options) => {
+    const globals = program.opts();
+    const payload = await runHeadless({
+      prompt: objective.join(" "),
+      model: options.model,
+      allowAll: Boolean(options.allowAll || globals.allowAll),
+      maxSteps: Number(options.maxSteps) > 0 ? Number(options.maxSteps) : Infinity,
+      json: Boolean(options.json),
+      quiet: Boolean(options.quiet),
+    });
+    if (!payload.ok) process.exitCode = 1;
+  });
 program.command("theme").description("Open the theme selector").action(runTheme);
 program.command("background").description("Set terminal background image (URL)").argument("[url]", "Image URL").action(setContentBackground);
+program
+  .command("history")
+  .alias("historico")
+  .description("Lista todas as conversas salvas")
+  .action(printHistory);
+
+program
+  .command("resume [codigo]")
+  .description("Retoma uma conversa salva (sem codigo abre o seletor na tela)")
+  .action((codigo) =>
+    runREPL({ allowAll: Boolean(program.opts().allowAll), resume: codigo || "pick" })
+  );
+
+program
+  .command("continue")
+  .alias("c")
+  .description("Continua a conversa mais recente")
+  .action(() => runREPL({ allowAll: Boolean(program.opts().allowAll), resume: "last" }));
 program.command("compact").description("Compact the current conversation context").action(compact);
 program.command("clear").description("Clear the conversation context").action(clearContext);
 program.command("status").description("Show account, balance and gateway status").action(showStatus);
 
-program.action(runREPL);
+program.action((options) =>
+  runREPL({
+    allowAll: Boolean(options.allowAll),
+    resume: options.continue ? "last" : options.resume || null,
+  })
+);
 program.parse();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kafox-cli",
-  "version": "0.3.0",
-  "description": "Kafox CLI in opencode style: scrollable TUI, markdown, modals, device login, models, balance",
+  "version": "0.7.0",
+  "description": "Kafox CLI: TUI com streaming, thinking, edit com diff, agent tools (files/shell), MCP e temas",
   "bin": {
     "kafox": "bin/kafox.js"
   },
@@ -20,6 +20,7 @@
     "inquirer": "8.2.6"
   },
   "scripts": {
-    "test": "node --test \"test/*.test.js\""
+    "test": "node --test \"test/*.test.js\"",
+    "smoke": "node test/e2e/tui.js"
   }
 }

package/src/agent.js

@@ -0,0 +1,385 @@
+const { chat } = require("./gateway");
+const {
+  TOOL_SPECS,
+  APPROVAL_REQUIRED,
+  executeTool,
+  describeToolCall,
+  previewToolChange,
+  summarizeOutput,
+} = require("./tools");
+const {
+  SUBAGENT_TOOL,
+  SUBAGENT_TOOL_NAME,
+  MAX_DEPTH,
+  normalizeTasks,
+  subagentPrompt,
+  describeSubagentCall,
+  recordRun,
+  DEFAULT_MAX_STEPS,
+} = require("./subagents");
+
+// Sem teto de passos: o agente continua ate terminar (ou ate o usuario parar
+// com Esc). `maxSteps` so vale quando alguem pede um limite de proposito.
+const MAX_STEPS = Infinity;
+const MAX_SUBAGENT_REPORT_CHARS = 6000;
+
+function parseArgs(raw) {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function systemPrompt(cwd, model) {
+  return [
+    "Voce e o kafox, uma CLI de terminal que conversa e executa tarefas no projeto do usuario.",
+    `Diretorio de trabalho: ${cwd}`,
+    `Modelo: ${model || "auto"}`,
+    "Ferramentas locais: read_file, list_dir, write_file, edit_file, run_command.",
+    "Para mudar um arquivo existente use edit_file (troca de trecho exato); write_file e para arquivo novo ou reescrita completa.",
+    "Ferramentas com nome mcp__<servidor>__<ferramenta> vem de servidores MCP conectados: use quando ajudarem.",
+    `spawn_subagent lanca subagentes com objetivo proprio em contexto separado (ate 3 em paralelo). Use para investigar varios pontos ao mesmo tempo, para auditoria/teste ou para tarefa longa; cada subagente devolve so o relatorio final.`,
+    "Nunca invente conteudo de arquivo: leia antes de editar. Prefira caminhos relativos.",
+    "Quem escreve ou executa passa por aprovacao do usuario, entao explique em uma frase o que vai fazer.",
+    "Responda no idioma do usuario, de forma direta, com Markdown.",
+  ].join("\n");
+}
+
+/**
+ * Roda um subagente: contexto proprio, ferramentas limitadas e relatorio final.
+ * Os eventos (onSubagentEvent) deixam a TUI mostrar o progresso ao vivo.
+ */
+async function runSubagentTask({
+  task,
+  index,
+  total,
+  model,
+  cwd,
+  approve,
+  autoAllowed,
+  signal,
+  depth,
+  onSubagentEvent,
+}) {
+  const started = Date.now();
+  const baseTools = TOOL_SPECS.filter((spec) => task.tools.includes(spec.function.name));
+  // Um nivel de subagente: o filho nao abre netos (evita recursao descontrolada).
+  const nested = [];
+
+  onSubagentEvent?.({
+    index,
+    total,
+    objective: task.objective,
+    phase: "start",
+    tools: task.tools,
+  });
+
+  let lastText = "";
+  try {
+    const result = await runAgent({
+      messages: [
+        {
+          role: "system",
+          content: subagentPrompt({ objective: task.objective, context: task.context, cwd, depth }),
+        },
+        { role: "user", content: task.objective },
+      ],
+      model,
+      cwd,
+      baseTools,
+      extraTools: nested,
+      maxSteps: task.maxSteps || DEFAULT_MAX_STEPS,
+      approve: approve
+        ? (name, args, context) =>
+            approve(name, args, { ...context, subagent: { index, objective: task.objective } })
+        : undefined,
+      autoApprove: autoAllowed,
+      signal,
+      depth: depth + 1,
+      subagents: depth + 1 < MAX_DEPTH,
+      onSubagentEvent,
+      onText: (chunk) => {
+        lastText += chunk;
+        onSubagentEvent?.({ index, total, phase: "text", text: chunk, objective: task.objective });
+      },
+      onReasoning: (chunk) =>
+        onSubagentEvent?.({ index, total, phase: "thought", text: chunk, objective: task.objective }),
+      onToolStart: ({ name, label }) =>
+        onSubagentEvent?.({ index, total, phase: "tool", tool: name, text: label, objective: task.objective }),
+      onToolResult: ({ name, ok }) =>
+        onSubagentEvent?.({ index, total, phase: "tool-done", tool: name, ok, objective: task.objective }),
+    });
+
+    const report = String(result.text || lastText || "").trim();
+    const body = report
+      ? report.slice(0, MAX_SUBAGENT_REPORT_CHARS)
+      : result.ok
+        ? "(subagente terminou sem texto final)"
+        : `(subagente falhou: ${result.error || "erro desconhecido"})`;
+    recordRun({
+      objective: task.objective,
+      tools: task.tools,
+      ok: Boolean(result.ok),
+      ms: Date.now() - started,
+      steps: result.steps || 0,
+      report: body,
+    });
+    onSubagentEvent?.({
+      index,
+      total,
+      objective: task.objective,
+      phase: "done",
+      ok: Boolean(result.ok),
+      ms: Date.now() - started,
+    });
+    return { index, objective: task.objective, ok: Boolean(result.ok), body, ms: Date.now() - started };
+  } catch (error) {
+    onSubagentEvent?.({
+      index,
+      total,
+      objective: task.objective,
+      phase: "done",
+      ok: false,
+      ms: Date.now() - started,
+    });
+    recordRun({
+      objective: task.objective,
+      tools: task.tools,
+      ok: false,
+      ms: Date.now() - started,
+      report: error.message,
+    });
+    return {
+      index,
+      objective: task.objective,
+      ok: false,
+      body: `(subagente falhou: ${error.message})`,
+      ms: Date.now() - started,
+    };
+  }
+}
+
+/** Dispara as tarefas (o que for independente roda em paralelo) e junta os relatorios. */
+async function runSubagents({ args, model, cwd, approve, autoAllowed, signal, depth, onSubagentEvent }) {
+  const tasks = normalizeTasks(args);
+  if (!tasks.length) {
+    return "Nenhuma tarefa recebida: informe `tasks: [{objective}]` (ou `objective`) para o subagente.";
+  }
+
+  const results = await Promise.all(
+    tasks.map((task, index) =>
+      runSubagentTask({
+        task,
+        index: index + 1,
+        total: tasks.length,
+        model: args?.model || model,
+        cwd,
+        approve,
+        autoAllowed,
+        signal,
+        depth,
+        onSubagentEvent,
+      })
+    )
+  );
+
+  return results
+    .map(
+      (result) =>
+        `[subagente ${result.index}/${results.length}] objetivo: ${result.objective}\n` +
+        `status: ${result.ok ? "ok" : "falhou"} · ${result.ms}ms\n${result.body}`
+    )
+    .join("\n\n---\n\n");
+}
+
+/**
+ * Roda o loop: modelo -> tool calls -> resultados -> modelo, ate a resposta final.
+ * Ferramenta que escreve, edita, executa ou vem de MCP passa por `approve`
+ * (async, true/false), a menos que `autoApprove` esteja ligado ("rodar tudo").
+ */
+async function runAgent({
+  messages = [],
+  model,
+  cwd = process.cwd(),
+  approve,
+  autoApprove = false,
+  extraTools = [],
+  baseTools = TOOL_SPECS,
+  mcp = null,
+  signal,
+  maxSteps = Infinity,
+  depth = 0,
+  subagents = true,
+  onText,
+  onReasoning,
+  onToolStart,
+  onToolResult,
+  onSubagentEvent,
+  onRetry,
+} = {}) {
+  const conversation = messages.map((message) => ({ ...message }));
+  if (!conversation.length || conversation[0].role !== "system") {
+    conversation.unshift({ role: "system", content: systemPrompt(cwd, model) });
+  }
+
+  // O subagente entra na lista de ferramentas enquanto a profundidade permitir.
+  const canSpawn = subagents && depth < MAX_DEPTH;
+  const tools = [
+    ...baseTools,
+    ...extraTools,
+    ...(canSpawn ? [SUBAGENT_TOOL] : []),
+  ];
+  // `autoApprove` pode ser um valor ou uma funcao: o "Permitir sempre" da TUI
+  // liga o modo no meio do loop, e o resto da execucao ja nao pergunta mais.
+  const autoAllowed = typeof autoApprove === "function" ? autoApprove : () => Boolean(autoApprove);
+  let last = { text: "", reasoning: "", ms: 0, usage: null };
+
+  for (let step = 0; step < (maxSteps || Infinity); step += 1) {
+    // Esc duas vezes na TUI aborta o signal: nao comeca outro passo.
+    if (signal?.aborted) {
+      return { ok: true, aborted: true, text: last.text, messages: conversation, steps: step };
+    }
+
+    const started = Date.now();
+    const result = await chat({
+      messages: conversation,
+      model,
+      tools,
+      signal,
+      onDelta: onText,
+      onReasoning,
+      onRetry,
+    });
+
+    if (!result.ok) {
+      return { ...result, aborted: result.code === "aborted", messages: conversation, text: last.text };
+    }
+
+    // Stream cortado no meio: guarda o que ja chegou e encerra o loop.
+    if (result.aborted) {
+      return {
+        ok: true,
+        aborted: true,
+        text: result.text || "",
+        reasoning: result.reasoning || "",
+        ms: result.ms,
+        messages: conversation,
+        steps: step + 1,
+      };
+    }
+
+    last = {
+      text: result.text,
+      reasoning: result.reasoning,
+      ms: result.ms,
+      usage: result.usage,
+      thoughtMs: Date.now() - started,
+    };
+    const assistant = { role: "assistant", content: result.text || "" };
+    if (result.toolCalls.length) assistant.tool_calls = result.toolCalls;
+    conversation.push(assistant);
+
+    if (!result.toolCalls.length) {
+      return {
+        ok: true,
+        ...last,
+        keyCreated: result.keyCreated,
+        messages: conversation,
+        steps: step + 1,
+      };
+    }
+
+    for (const call of result.toolCalls) {
+      const name = call?.function?.name || "";
+      const args = parseArgs(call?.function?.arguments);
+      const fromMcp = Boolean(mcp?.has?.(name));
+      const isSubagent = name === SUBAGENT_TOOL_NAME;
+      // O subagente em si nao pede aprovacao: quem escreve/executa dentro dele
+      // continua passando pelo portao normal.
+      const needsApproval = !isSubagent && (APPROVAL_REQUIRED.has(name) || fromMcp);
+      const callId = call.id || `call_${step}_${name}`;
+
+      let change = null;
+      try {
+        change = previewToolChange(name, args, { cwd });
+      } catch {
+        change = null;
+      }
+
+      const label = isSubagent ? describeSubagentCall(args) : describeToolCall(name, args);
+      const tasks = isSubagent ? normalizeTasks(args) : null;
+
+      onToolStart?.({
+        id: callId,
+        name,
+        args,
+        label,
+        change,
+        fromMcp,
+        needsApproval,
+        subagent: tasks ? { count: tasks.length, objectives: tasks.map((task) => task.objective) } : null,
+      });
+
+      const gate = needsApproval && !autoAllowed();
+      let allowed = true;
+      if (gate) {
+        allowed = approve ? Boolean(await approve(name, args, { change, fromMcp })) : false;
+      }
+
+      const toolStarted = Date.now();
+      let output;
+      if (!allowed) {
+        output = "O usuario negou a execucao desta ferramenta. Peca instrucoes se precisar.";
+      } else if (isSubagent) {
+        output = await runSubagents({
+          args,
+          model,
+          cwd,
+          approve,
+          autoAllowed,
+          signal,
+          depth,
+          onSubagentEvent: (event) => onSubagentEvent?.({ ...event, id: callId }),
+        });
+      } else {
+        try {
+          output = await executeTool(name, args, { cwd, mcp });
+        } catch (error) {
+          output = `Erro: ${error.message}`;
+        }
+      }
+
+      onToolResult?.({
+        id: callId,
+        name,
+        args,
+        output,
+        change,
+        ok: allowed && !String(output).startsWith("Erro:"),
+        skipped: !allowed,
+        fromMcp,
+        ms: Date.now() - toolStarted,
+        summary: summarizeOutput(output),
+        subagent: tasks ? { count: tasks.length } : null,
+      });
+
+      conversation.push({
+        role: "tool",
+        tool_call_id: callId,
+        content: String(output),
+      });
+    }
+  }
+
+  return {
+    ok: false,
+    error: `Limite de ${maxSteps} passos do agente atingido.`,
+    ...last,
+    messages: conversation,
+  };
+}
+
+module.exports = { runAgent, runSubagents, MAX_STEPS, systemPrompt };