liberty-code-cli 1.0.0 → 2.0.0

package/src/repl.js

@@ -0,0 +1,285 @@
+'use strict';
+/**
+ * REPL interativo — equivalente ao loop principal que antes vivia inteiro
+ * dentro de cmdChat() em bin/liberty.js. Agora é só orquestração: cada
+ * feature nova (permissões, memória, sessões, hooks, skills, mcp,
+ * subagentes) vive no seu próprio módulo, e este arquivo os conecta.
+ */
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const pkg = require('../package.json');
+const { PERMISSION_MODES, MAX_TOOL_ITERATIONS } = require('./constants');
+const { paint, banner } = require('./ui');
+const { PermissionEngine } = require('./permissions');
+const { buildIgnoreEngine } = require('./ignoreEngine');
+const memory = require('./memory');
+const sessionStore = require('./session');
+const hooks = require('./hooks');
+const { discoverSkills, buildSkillsManifestBlock } = require('./skills');
+const { McpManager } = require('./mcp');
+const { buildToolSchemas } = require('./tools');
+const { runAgentLoop } = require('./engine');
+const { runSubagent } = require('./subagents');
+const { renderTodos } = require('./tools/todo-tool');
+
+function confirm(rl, label) {
+  return new Promise(resolve => rl.question(label, a => resolve(['y', 'yes', 's', 'sim'].includes(a.trim().toLowerCase()))));
+}
+
+async function start(config, opts = {}) {
+  const cwd = process.cwd();
+  memory.ensureGlobalDir();
+
+  const permissions = new PermissionEngine(opts.permissionMode || PERMISSION_MODES.DEFAULT);
+  const ignoreEngine = buildIgnoreEngine(cwd);
+  const skills = discoverSkills(cwd);
+  const mcpManager = new McpManager();
+
+  console.log(banner(pkg.version, cwd));
+  console.log(paint('gray', `   modo: ${permissions.describeMode()}`));
+
+  const { connected, failed } = await mcpManager.connectAll(cwd);
+  if (connected.length || failed.length) mcpManager.printSummary(connected, failed);
+
+  const memoryBlock = memory.loadHierarchicalMemory(cwd);
+  const skillsBlock = buildSkillsManifestBlock(skills, cwd);
+  const sessionStartHook = hooks.runHooks('SessionStart', { cwd }, cwd);
+  sessionStartHook.infoLines.forEach(l => console.log(l));
+
+  const primingParts = [
+    memoryBlock,
+    skillsBlock,
+    sessionStartHook.rawOutputs.length ? `### Informações do início da sessão (hook SessionStart)\n${sessionStartHook.rawOutputs.join('\n\n')}` : null,
+  ].filter(Boolean);
+
+  let messages = [];
+  let todos = [];
+  let sessionId = sessionStore.newSessionId();
+
+  if (opts.resumeId) {
+    const loaded = sessionStore.loadSession(cwd, opts.resumeId);
+    if (loaded) {
+      messages = loaded.messages;
+      todos = loaded.todos || [];
+      sessionId = loaded.id;
+      console.log(paint('gray', `   sessão retomada: ${loaded.id} (${messages.length} mensagens)`));
+    } else {
+      console.log(paint('yellow', `   nenhuma sessão encontrada para "${opts.resumeId}" — começando uma nova.`));
+    }
+  }
+
+  if (!messages.length && primingParts.length) {
+    messages = [
+      { role: 'user', content: `[Contexto inicial da sessão — fornecido automaticamente, não é um pedido, só referência]\n\n${primingParts.join('\n\n---\n\n')}` },
+      { role: 'assistant', content: 'Entendido, vou levar esse contexto em conta.' },
+    ];
+  }
+  const primedMessages = messages.map(m => ({ ...m }));
+
+  if (memory.hasProjectMemory(cwd)) console.log(paint('gray', '   LIBERTY.md do projeto carregado'));
+  if (memory.hasGlobalMemory()) console.log(paint('gray', '   LIBERTY.md global carregado'));
+  if (skills.length) console.log(paint('gray', `   ${skills.length} skill(s) disponível(is) — /skills pra ver`));
+  console.log(paint('gray', '\nDigite seu pedido  ·  /help pra ver comandos  ·  # anota algo na memória  ·  Ctrl+C cancela/sai\n'));
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const backgroundProcs = [];
+  let currentAbort = null;
+
+  const ctx = {
+    cwd, rl, permissions, ignoreEngine, hooks, todos, backgroundProcs,
+    mcpManager, allowSubagents: true, token: config.token,
+  };
+  ctx.runSubagent = (args) => runSubagent(args, ctx);
+
+  rl.on('SIGINT', () => {
+    if (currentAbort) { currentAbort.abort(); console.log(paint('gray', '\n(cancelado)')); }
+    else { rl.close(); }
+  });
+
+  function autosave() {
+    try { sessionStore.saveSession(cwd, sessionId, { messages, todos, cwd }); } catch { /* não trava o REPL por falha ao salvar sessão */ }
+  }
+
+  function currentTools() {
+    return buildToolSchemas({ mode: permissions.mode, includeTask: true, mcpTools: mcpManager.getToolSchemas() });
+  }
+
+  async function runTurn(userText) {
+    messages.push({ role: 'user', content: userText });
+    currentAbort = new AbortController();
+    let result;
+    try {
+      result = await runAgentLoop({
+        messages, token: config.token, tools: currentTools(), ctx,
+        maxIterations: MAX_TOOL_ITERATIONS, verbose: true, signal: currentAbort.signal,
+      });
+    } catch (e) {
+      console.log(paint('red', `\n❌ ${e.message}\n`));
+      currentAbort = null;
+      autosave();
+      return;
+    }
+    currentAbort = null;
+
+    if (result.cancelled) { autosave(); return; }
+
+    if (result.stoppedByLimit) {
+      console.log(paint('yellow', `\n⚠ ${result.limitMessage}\n`));
+      messages.push({ role: 'assistant', content: result.limitMessage });
+      autosave();
+      return;
+    }
+
+    console.log('\n' + paint('bold', paint('gray', '● ')) + result.finalText + '\n');
+    if (todos.length) renderTodos(todos);
+    hooks.runHooks('Stop', { cwd }, cwd).infoLines.forEach(l => console.log(l));
+    autosave();
+
+    if (permissions.mode === PERMISSION_MODES.PLAN) {
+      const proceed = await confirm(rl, paint('cyan', '\nSair do modo plano e executar o que foi combinado? [y/N] '));
+      if (proceed) {
+        permissions.setMode(PERMISSION_MODES.DEFAULT);
+        console.log(paint('gray', `   modo alterado para: ${permissions.describeMode()}\n`));
+        await runTurn('Prossiga executando o plano combinado acima.');
+      }
+    }
+  }
+
+  function printHelp() {
+    console.log(paint('gray', `
+Comandos:
+  /help                 Mostra estes comandos
+  /clear                Limpa o histórico (mantém memória/skills carregadas)
+  /exit, /quit           Sai
+  /init                  Explora o projeto e cria/atualiza o LIBERTY.md
+  /memory                Mostra a memória (global + projeto) carregada agora
+  /mode [nome]           Mostra ou troca o modo: default, acceptEdits, bypassPermissions, plan
+  /sessions              Lista sessões salvas deste projeto
+  /resume <id|latest>    Retoma uma sessão salva
+  /skills                Lista skills carregadas (.liberty/skills)
+  /mcp                   Lista servidores MCP conectados (.liberty/mcp.json)
+  /bg                    Lista processos em background desta sessão
+  # texto                Anota "texto" no LIBERTY.md do projeto sem enviar ao modelo
+
+Ctrl+C durante uma resposta cancela só aquela resposta; parado no prompt, sai.
+`));
+  }
+
+  const promptUser = () => rl.question(paint('cyan', '› '), async (input) => {
+    const trimmed = input.trim();
+    if (!trimmed) return promptUser();
+
+    if (trimmed.startsWith('#')) {
+      const note = trimmed.slice(1).trim();
+      if (note) {
+        const file = memory.appendQuickNote(cwd, note);
+        console.log(paint('gray', `   anotado em ${path.relative(cwd, file)}\n`));
+      }
+      return promptUser();
+    }
+
+    if (trimmed === '/exit' || trimmed === '/quit') { rl.close(); return; }
+    if (trimmed === '/help') { printHelp(); return promptUser(); }
+
+    if (trimmed === '/clear') {
+      messages = primedMessages.map(m => ({ ...m }));
+      todos.length = 0;
+      sessionId = sessionStore.newSessionId();
+      console.log(paint('gray', '\n(histórico limpo — memória/skills continuam carregadas)\n'));
+      return promptUser();
+    }
+
+    if (trimmed === '/memory') {
+      const block = memory.loadHierarchicalMemory(cwd);
+      console.log(block ? '\n' + paint('gray', block) + '\n' : paint('gray', '\nNenhuma memória carregada ainda. Use /init pra gerar uma, ou crie LIBERTY.md na raiz do projeto.\n'));
+      return promptUser();
+    }
+
+    if (trimmed === '/init') {
+      await runTurn(
+        'Explore a estrutura deste projeto (list_directory recursivo, leia package.json/requirements.txt/etc, identifique stack e scripts de build/teste/lint) e depois escreva um arquivo LIBERTY.md na raiz com: visão geral do projeto, comandos de build/teste/lint, convenções de código observadas e o que evitar. Se já existir um LIBERTY.md, releia-o primeiro e proponha uma versão atualizada em vez de ignorar o que já está lá.'
+      );
+      return promptUser();
+    }
+
+    if (trimmed.startsWith('/mode')) {
+      const target = trimmed.split(/\s+/)[1];
+      if (!target) {
+        console.log(paint('gray', `\nModo atual: ${permissions.describeMode()}\nOpções: default, acceptEdits, bypassPermissions, plan\n`));
+        return promptUser();
+      }
+      if (target === PERMISSION_MODES.BYPASS) {
+        const ok = await confirm(rl, paint('red', 'bypassPermissions aprova QUALQUER escrita de arquivo ou comando sem perguntar. Confirma? [y/N] '));
+        if (!ok) { console.log(paint('gray', 'Mantido no modo anterior.\n')); return promptUser(); }
+      }
+      try {
+        permissions.setMode(target);
+        console.log(paint('gray', `\nModo alterado: ${permissions.describeMode()}\n`));
+      } catch (e) { console.log(paint('red', `\n${e.message}\n`)); }
+      return promptUser();
+    }
+
+    if (trimmed === '/sessions') {
+      const list = sessionStore.listSessions(cwd);
+      console.log(list.length
+        ? '\n' + list.map(s => paint('gray', `  ${s.id}  (${s.messageCount} msgs, ${s.updatedAt})  `) + s.preview).join('\n') + '\n'
+        : paint('gray', '\nNenhuma sessão salva ainda pra este projeto.\n'));
+      return promptUser();
+    }
+
+    if (trimmed.startsWith('/resume')) {
+      const id = trimmed.split(/\s+/)[1] || 'latest';
+      const loaded = sessionStore.loadSession(cwd, id);
+      if (!loaded) { console.log(paint('red', `\nSessão "${id}" não encontrada. Use /sessions pra ver as disponíveis.\n`)); return promptUser(); }
+      messages = loaded.messages;
+      todos.length = 0; todos.push(...(loaded.todos || []));
+      sessionId = loaded.id;
+      if (todos.length) renderTodos(todos);
+      console.log(paint('gray', `\nSessão retomada: ${loaded.id} (${messages.length} mensagens)\n`));
+      return promptUser();
+    }
+
+    if (trimmed === '/skills') {
+      console.log(skills.length
+        ? '\n' + skills.map(s => paint('gray', `  [${s.scope}] `) + paint('bold', s.name) + paint('gray', ` — ${s.description}`)).join('\n') + '\n'
+        : paint('gray', '\nNenhuma skill encontrada. Crie .liberty/skills/<nome>/SKILL.md (ou ~/.libertycode/skills/<nome>/SKILL.md pra reusar entre projetos).\n'));
+      return promptUser();
+    }
+
+    if (trimmed === '/mcp') {
+      const names = [...mcpManager.servers.keys()];
+      console.log(names.length
+        ? '\n' + names.map(n => paint('gray', `  ${n}`)).join('\n') + '\n'
+        : paint('gray', '\nNenhum servidor MCP conectado. Configure .liberty/mcp.json (mesmo formato do mcpServers do Claude Code).\n'));
+      return promptUser();
+    }
+
+    if (trimmed === '/bg') {
+      console.log(backgroundProcs.length
+        ? '\n' + backgroundProcs.map(p => paint('gray', `  PID ${p.pid}  ${p.command}  → ${p.logFile}`)).join('\n') + '\n'
+        : paint('gray', '\nNenhum processo em background nesta sessão.\n'));
+      return promptUser();
+    }
+
+    const promptHook = hooks.runHooks('UserPromptSubmit', { cwd, prompt: trimmed }, cwd);
+    promptHook.infoLines.forEach(l => console.log(l));
+    if (promptHook.blocked) { console.log(paint('red', `\n🚫 ${promptHook.reason}\n`)); return promptUser(); }
+    const finalInput = promptHook.rawOutputs.length
+      ? `${input}\n\n[Contexto adicional de hook UserPromptSubmit]\n${promptHook.rawOutputs.join('\n')}`
+      : input;
+
+    await runTurn(finalInput);
+    promptUser();
+  });
+
+  rl.on('close', async () => {
+    try { await mcpManager.disconnectAll(); } catch { /* processo já está saindo mesmo */ }
+    console.log(paint('gray', '\nAté mais!'));
+    process.exit(0);
+  });
+
+  promptUser();
+}
+
+module.exports = { start };

package/src/session.js

@@ -0,0 +1,82 @@
+'use strict';
+/**
+ * Sessões retomáveis — equivalente ao --continue / --resume do Claude Code.
+ *
+ * ANTES: `messages` vivia só na memória do processo; fechar o terminal (ou
+ * o Ctrl+C do dia seguinte) perdia toda a conversa e o contexto acumulado.
+ *
+ * AGORA: depois de cada turno completo, a sessão inteira (mensagens + todos)
+ * é salva em ~/.libertycode/sessions/<projeto>/<id>.json. `liberty --continue`
+ * retoma a última sessão daquele diretório; `liberty --resume` lista as
+ * sessões recentes pra escolher; `/sessions` faz o mesmo de dentro do REPL.
+ *
+ * Fica em ~/.libertycode (fora do projeto) de propósito — sessão pode conter
+ * trechos de código/arquivos lidos, não é algo pra acabar commitado sem querer.
+ */
+const fs = require('fs');
+const path = require('path');
+const { SESSIONS_ROOT, slugifyProjectPath, ensureDir } = require('./constants');
+
+function sessionsDirFor(cwd) {
+  return ensureDir(path.join(SESSIONS_ROOT, slugifyProjectPath(cwd)));
+}
+
+function newSessionId() {
+  const now = new Date();
+  const stamp = now.toISOString().replace(/[:.]/g, '-');
+  return `${stamp}-${Math.random().toString(36).slice(2, 7)}`;
+}
+
+function sessionPath(cwd, id) {
+  return path.join(sessionsDirFor(cwd), `${id}.json`);
+}
+
+function saveSession(cwd, id, { messages, todos, cwd: cwdField }) {
+  const file = sessionPath(cwd, id);
+  const existing = fs.existsSync(file) ? safeReadJson(file) : null;
+  const payload = {
+    id,
+    cwd: cwdField || cwd,
+    createdAt: existing?.createdAt || new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    messages,
+    todos: todos || [],
+  };
+  fs.writeFileSync(file, JSON.stringify(payload, null, 2), 'utf8');
+  return file;
+}
+
+function safeReadJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+/** Lista sessões do projeto atual, mais recente primeiro. */
+function listSessions(cwd, limit = 15) {
+  const dir = sessionsDirFor(cwd);
+  const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+  const sessions = files.map(f => safeReadJson(path.join(dir, f))).filter(Boolean);
+  sessions.sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''));
+  return sessions.slice(0, limit).map(s => ({
+    id: s.id,
+    updatedAt: s.updatedAt,
+    messageCount: (s.messages || []).length,
+    preview: firstUserPreview(s.messages),
+  }));
+}
+
+function firstUserPreview(messages) {
+  const firstUser = (messages || []).find(m => m.role === 'user' && typeof m.content === 'string' && !m.content.startsWith('[Contexto do projeto'));
+  if (!firstUser) return '(sem mensagens do usuário ainda)';
+  return firstUser.content.slice(0, 70).replace(/\n/g, ' ');
+}
+
+function loadSession(cwd, id) {
+  if (id === 'latest') {
+    const [latest] = listSessions(cwd, 1);
+    if (!latest) return null;
+    return safeReadJson(sessionPath(cwd, latest.id));
+  }
+  return safeReadJson(sessionPath(cwd, id));
+}
+
+module.exports = { newSessionId, saveSession, listSessions, loadSession, sessionsDirFor };

package/src/skills.js

@@ -0,0 +1,94 @@
+'use strict';
+/**
+ * Skills — equivalente às Skills do Claude Code.
+ *
+ * NOVO (v2): conceito não existia pro CLI (o "skills/" que já existia no
+ * server.js é outra coisa — prompts internos do servidor, não isso aqui).
+ *
+ * Ideia central, igual ao Claude Code: NÃO carregar o conteúdo de todas as
+ * skills na mensagem de sistema (isso ia inflar o contexto rápido). Em vez
+ * disso:
+ *   1. No início da sessão, escaneia .liberty/skills/*\/SKILL.md (projeto) e
+ *      ~/.libertycode/skills/*\/SKILL.md (global/reutilizável entre projetos).
+ *   2. Monta só um MANIFESTO curto (nome + descrição de 1 linha de cada) e
+ *      injeta isso no contexto.
+ *   3. O modelo decide, pelo próprio manifesto, se alguma skill combina com o
+ *      pedido do usuário — e se sim, abre o arquivo completo com a ferramenta
+ *      read_file que ele já tem (não precisa de uma ferramenta nova).
+ *
+ * Cada SKILL.md pode ter um front-matter simples:
+ *   ---
+ *   name: revisar-pr
+ *   description: Use ao revisar um Pull Request — checklist de segurança, testes e estilo.
+ *   ---
+ * Se não tiver front-matter, usa a 1ª linha "# Título" como nome e a 1ª
+ * linha de texto depois dela como descrição (fallback tolerante).
+ */
+const fs = require('fs');
+const path = require('path');
+const { projectSkillsDir, GLOBAL_SKILLS_DIR } = require('./constants');
+
+function parseFrontMatter(content) {
+  const fm = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+  if (!fm) return null;
+  const meta = {};
+  fm[1].split('\n').forEach(line => {
+    const m = line.match(/^(\w[\w-]*)\s*:\s*(.+)$/);
+    if (m) meta[m[1].trim()] = m[2].trim();
+  });
+  return meta;
+}
+
+function fallbackMeta(content, dirName) {
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  const afterTitle = content.split('\n').slice(1).find(l => l.trim() && !l.startsWith('#'));
+  return {
+    name: titleMatch ? titleMatch[1].trim() : dirName,
+    description: (afterTitle || 'Sem descrição.').trim().slice(0, 160),
+  };
+}
+
+function scanSkillsDir(dir, scope) {
+  const found = [];
+  if (!fs.existsSync(dir)) return found;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const skillFile = path.join(dir, entry.name, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) continue;
+    try {
+      const content = fs.readFileSync(skillFile, 'utf8');
+      const meta = parseFrontMatter(content) || fallbackMeta(content, entry.name);
+      found.push({
+        name: meta.name || entry.name,
+        description: meta.description || '(sem descrição)',
+        path: skillFile,
+        scope,
+      });
+    } catch { /* SKILL.md ilegível — ignora essa skill, não derruba o resto */ }
+  }
+  return found;
+}
+
+function discoverSkills(cwd) {
+  return [
+    ...scanSkillsDir(GLOBAL_SKILLS_DIR, 'global'),
+    ...scanSkillsDir(projectSkillsDir(cwd), 'projeto'),
+  ];
+}
+
+function buildSkillsManifestBlock(skills, cwd) {
+  if (!skills.length) return null;
+  const lines = skills.map(s => {
+    const rel = path.relative(cwd, s.path);
+    return `- **${s.name}** (${s.scope}, leia com read_file em \`${rel}\`): ${s.description}`;
+  });
+  return [
+    '### Skills disponíveis',
+    'Antes de tarefas que envolvam código, arquivos ou comandos, verifique se alguma skill abaixo combina com o pedido.',
+    'Se combinar, leia o SKILL.md completo (read_file) ANTES de agir — ele tem instruções específicas deste projeto/usuário que você não tem por padrão.',
+    'Não leia skills irrelevantes só por precaução; isso desperdiça contexto.',
+    ...lines,
+  ].join('\n');
+}
+
+module.exports = { discoverSkills, buildSkillsManifestBlock };

package/src/subagents.js

@@ -0,0 +1,70 @@
+'use strict';
+/**
+ * Subagentes — equivalente à ferramenta Task do Claude Code.
+ *
+ * NOVO (v2): antes cada chamada de ferramenta acontecia dentro da MESMA
+ * conversa/contexto. Isso é ruim pra tarefas tipo "vasculhe o repositório
+ * inteiro procurando todo lugar que usa a função X" — o histórico de
+ * list_directory/read_file/grep_search intermediários (que pode ser MUITO
+ * texto) fica misturado com a conversa principal pro resto da sessão, mesmo
+ * que só o resultado final importe.
+ *
+ * O subagente resolve isso: roda o MESMO engine.runAgentLoop, mas com:
+ *   - histórico próprio, começando do zero (só o `prompt` recebido, sem ver
+ *     nada da conversa principal — isolamento real, não só "resumo")
+ *   - ferramentas restritas por subagent_type
+ *   - teto de iterações menor (é uma tarefa focada, não uma conversa livre)
+ *   - allowSubagents:false (profundidade máxima 1 — subagente não dispara
+ *     outro subagente, evita explosão de custo/recursão)
+ * e devolve pro agente principal só o TEXTO FINAL — o resto (chamadas de
+ * ferramenta intermediárias) fica só no log do terminal, nunca entra na
+ * conversa principal.
+ */
+const { MAX_SUBAGENT_ITERATIONS } = require('./constants');
+const { buildSubagentToolSchemas } = require('./tools');
+const { runAgentLoop } = require('./engine');
+const { paint, spinner } = require('./ui');
+
+function lastAssistantText(messages) {
+  const last = [...messages].reverse().find(m => m.role === 'assistant' && typeof m.content === 'string' && m.content.trim());
+  return last ? last.content : '(sem progresso textual registrado)';
+}
+
+async function runSubagent(args, parentCtx) {
+  const { description, prompt, subagent_type = 'general' } = args;
+  if (!prompt || !prompt.trim()) throw new Error('prompt é obrigatório e precisa ser autocontido — o subagente não vê o histórico da conversa principal.');
+  if (!['general', 'read-only-researcher'].includes(subagent_type)) throw new Error('subagent_type deve ser "general" ou "read-only-researcher".');
+
+  console.log(paint('magenta', `\n🤖 Subagente [${subagent_type}]: `) + paint('bold', description || prompt.slice(0, 60)));
+  const spin = spinner(`   trabalhando`);
+
+  const mcpTools = parentCtx.mcpManager ? parentCtx.mcpManager.getToolSchemas() : [];
+  const tools = buildSubagentToolSchemas(subagent_type, mcpTools);
+  const subMessages = [{ role: 'user', content: prompt }];
+  const subCtx = { ...parentCtx, allowSubagents: false, todos: [] }; // profundidade máx. 1; lista de todos própria, não polui a principal
+  const systemPromptSuffix = [
+    'Você é um SUBAGENTE disparado pela ferramenta "task" de outra instância sua.',
+    'Você NÃO tem acesso ao histórico da conversa principal — apenas à instrução do usuário abaixo. Se algo essencial não foi dito, assuma o caminho mais razoável e deixe isso explícito na resposta final.',
+    'Ao terminar, responda com um RESUMO CONCISO e acionável do que encontrou/fez — é a ÚNICA parte que a conversa principal vai ver, os passos intermediários se perdem.',
+    subagent_type === 'read-only-researcher' ? 'Você só tem ferramentas de leitura/busca — não pode editar arquivos nem rodar comandos.' : '',
+  ].filter(Boolean).join(' ');
+
+  let result;
+  try {
+    result = await runAgentLoop({
+      messages: subMessages, token: parentCtx.token, tools, systemPromptSuffix,
+      ctx: subCtx, maxIterations: MAX_SUBAGENT_ITERATIONS, verbose: false,
+    });
+  } finally {
+    spin.stop();
+  }
+
+  if (result.cancelled) return '[Subagente cancelado pelo usuário.]';
+  if (result.stoppedByLimit) {
+    return `[Subagente atingiu o limite de ${MAX_SUBAGENT_ITERATIONS} passos sem concluir formalmente. Progresso registrado até aqui:]\n${lastAssistantText(subMessages)}`;
+  }
+  console.log(paint('gray', `   ✓ subagente concluído`));
+  return result.finalText || '(subagente não retornou texto)';
+}
+
+module.exports = { runSubagent };

package/src/tools/exec-tools.js

@@ -0,0 +1,73 @@
+'use strict';
+/**
+ * run_command — v1 só tinha execução síncrona bloqueante (execSync), o que
+ * é um problema real pra qualquer comando de longa duração: `npm run dev`,
+ * um servidor, um watcher... o comando trava o loop do agente até terminar
+ * (ou até o timeout de 60s matar ele), e nunca devolve controle.
+ *
+ * NOVO: run_in_background:true usa spawn() destacado, redireciona
+ * stdout+stderr pra um arquivo de log em .liberty/logs/ e devolve o controle
+ * IMEDIATAMENTE com o caminho do log + PID — o modelo pode continuar a
+ * conversa e checar o log depois com read_file (ou grep_search) quando quiser
+ * saber se o servidor subiu.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execSync, spawn } = require('child_process');
+const { RUN_COMMAND_TIMEOUT_MS, RUN_COMMAND_MAX_BUFFER, projectLogsDir, ensureDir } = require('../constants');
+const { paint } = require('../ui');
+
+async function toolRunCommand(args, ctx) {
+  console.log(paint('yellow', '\n💻 Executar comando: ') + paint('bold', args.command) +
+    (args.run_in_background ? paint('gray', '  (background)') : ''));
+
+  const hookRes = ctx.hooks.runHooks('PreToolUse', { toolName: 'run_command', args, cwd: ctx.cwd }, ctx.cwd);
+  hookRes.infoLines.forEach(l => console.log(l));
+  if (hookRes.blocked) return `[Bloqueado por hook: ${hookRes.reason}]`;
+
+  const ok = await ctx.permissions.check('run', args.command, '   Permitir?', ctx.rl);
+  if (!ok) return '[Usuário negou a execução deste comando.]';
+
+  const result = args.run_in_background
+    ? runInBackground(args.command, ctx)
+    : runForeground(args.command, ctx);
+
+  ctx.hooks.runHooks('PostToolUse', { toolName: 'run_command', args, cwd: ctx.cwd }, ctx.cwd)
+    .infoLines.forEach(l => console.log(l));
+  return result;
+}
+
+function runForeground(command, ctx) {
+  try {
+    const output = execSync(command, {
+      cwd: ctx.cwd, encoding: 'utf8',
+      timeout: RUN_COMMAND_TIMEOUT_MS, maxBuffer: RUN_COMMAND_MAX_BUFFER,
+    });
+    return output || '(comando executado sem output)';
+  } catch (e) {
+    if (e.signal === 'SIGTERM' || e.killed) {
+      return `[Comando interrompido após ${RUN_COMMAND_TIMEOUT_MS / 1000}s (timeout). Se é um processo de longa duração (servidor, watcher), rode com run_in_background:true.]`;
+    }
+    return `Erro (exit ${e.status ?? '?'}):\n${(e.stdout || '') + (e.stderr || e.message)}`;
+  }
+}
+
+function runInBackground(command, ctx) {
+  const logsDir = ensureDir(projectLogsDir(ctx.cwd));
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const logFile = path.join(logsDir, `${stamp}.log`);
+  const fd = fs.openSync(logFile, 'a');
+
+  const child = spawn(command, {
+    cwd: ctx.cwd, shell: true, detached: true, stdio: ['ignore', fd, fd],
+  });
+  child.unref();
+  const relLog = path.relative(ctx.cwd, logFile);
+  ctx.backgroundProcs = ctx.backgroundProcs || [];
+  ctx.backgroundProcs.push({ pid: child.pid, command, logFile: relLog, startedAt: new Date().toISOString() });
+
+  return `Processo iniciado em background (PID ${child.pid}). Saída sendo gravada em ${relLog} — use read_file nesse caminho pra acompanhar. ` +
+    `Este comando NÃO é encerrado automaticamente ao fim da sessão; para parar, rode "kill ${child.pid}" (Linux/Mac) via run_command.`;
+}
+
+module.exports = { toolRunCommand };