Summon CLI

O que Summon CLI faz?

Objetivo

Entregar a solicitação atual completa para um CLI de Agente externo configurado. O agente externo pode ser Claude Code, Grok CLI, Gemini CLI, Codex CLI ou outros agentes que vierem a ser adicionados; API, modelo, protocolo de frontend ou background, parâmetros de inicialização e a Skill de destino são todos determinados pela configuração dentro desta Skill, não sendo fixados na descrição do comportamento.

O usuário invoca esta Skill explicitamente com $summon-cli. Atualmente, também existe uma rota automática de escrita: quando o Codex identifica que o usuário deseja criar posts curtos, artigos, apresentações de projetos ou outros textos publicáveis, ele lê a configuração da tarefa writing e delega; esta rota automática é também autorizada pelo AGENTS.md da máquina local. Outras tarefas não serão delegadas automaticamente apenas pela existência desta Skill.

Modo de Funcionamento

Após o primeiro uso ou ao copiar esta Skill para outra máquina, execute a descoberta local no diretório desta Skill:

& '<Diretório desta Skill>\scripts\summon.ps1' setup

No macOS, Linux ou WSL, use:

sh '<Diretório desta Skill>/scripts/summon.sh' setup

O comando setup apenas descobre o Python, CLIs de Agente, Skills e terminais gráficos presentes no sistema atual e grava os caminhos absolutos no arquivo config/config.local.json, que é ignorado pelo Git dentro desta Skill; ele não instala software, move chaves ou modifica configurações públicas. Em seguida, execute show e doctor para verificar os resultados.

A configuração é selecionada com base na tarefa, profile e Skill indicados pelo usuário; quando o usuário não especifica nada, a seleção é feita de acordo com a descrição da tarefa usando as rotas já configuradas. Uma tarefa pode não usar Skill alguma, ou usar exatamente uma Skill; não é possível passar múltiplas Skills para o agente externo em uma única chamada. Quando a tarefa exige uma Skill, mas nem o usuário nem a configuração padrão a definiram, o sistema pergunta ao usuário qual Skill usar desta vez, sem adivinhar e sem invocar candidatos simultaneamente.

Suplemento de Pesquisa na Web pelo Codex

Quando o codex_web da configuração da tarefa for supplement, é o Codex atual quem realiza a descoberta de materiais públicos antes da chamada. Primeiro, leia completamente a solicitação existente, os materiais do usuário e os objetos locais para determinar se ainda faltam materiais públicos para concluir a tarefa; se o conteúdo existente for suficiente, a transição é feita imediatamente; a pesquisa na web só ocorre se houver realmente uma lacuna. Utilize o texto original relevante das páginas web ou o contexto necessário, juntamente com os links de origem, na transição, preservando a identidade desses materiais, sem adicionar frases centrais extraídas pelo Codex, ângulos recomendados, narrativas explicativas ou conteúdo pré-escrito.

Quando o Codex julgar que o conteúdo existente ou o suplemento desta rodada é suficiente, a descoberta de materiais públicos termina aqui; o agente externo não repete a busca e executa a fase atual da Skill de destino conforme a solicitação do usuário nesta rodada. Se o usuário pedir para entregar um esboço primeiro e confirmar antes de escrever o texto completo, apenas a fase de esboço será executada nesta rodada, sem preparar exemplos, ganchos, texto completo, revisões ou modificações antecipadamente. Somente se ainda faltarem materiais públicos necessários para concluir a fase atual é que esses materiais específicos serão passados para o agente externo continuar a busca. A pesquisa na web é usada apenas para suplementar materiais, não para verificar item por item o conteúdo do usuário, nem para gerar relatórios de verificação de fatos.

Se o usuário proibir explicitamente a pesquisa na web ou exigir o uso apenas de materiais existentes, a etapa de suplemento pela web é pulada. Outras tarefas só terão a descoberta de materiais públicos tratada pelo Codex se a configuração específica da tarefa assim o permitir.

Entrega ao Agente Externo

O que é entregue ao agente externo são as palavras originais do usuário e os materiais reais que ainda precisam ser executados por ele, não o histórico completo de correções. Quando mensagens posteriores do usuário corrigem a direção anterior, as instruções, ângulos e produções do assistente que se tornaram inválidos são removidos diretamente; o restante das palavras originais do usuário, o texto das fontes, a ordem e a identidade das fontes permanecem inalterados. Quando o significado atual está distribuído em várias mensagens, apenas as frases originais do usuário que ainda são válidas e ainda precisam ser executadas pelo agente externo são selecionadas, sem que o Codex as reescreva como resumo, síntese, frase central ou estrutura narrativa.

A entrada da chamada inclui apenas:

• As palavras originais do usuário e os materiais de origem que ainda precisam ser executados pelo agente externo;
• Os materiais de pesquisa na web realmente utilizados pelo Codex nesta rodada, com links;
• As instruções de transição necessárias.

Para tarefas de escrita ou delegação de conteúdo, se os materiais estiverem em tarefas anteriores, arquivos locais ou projetos acessíveis ao Codex atual, o Codex lê o conteúdo realmente necessário antes da chamada e envia o texto original adotado junto com a transição. Instruções como "leia este histórico", "abra estes arquivos", "examine este projeto e colete material" que já foram executadas pelo Codex atual não são repetidas como tarefas pendentes para o agente externo; substituir tais instruções por materiais reais não é uma reescrita dos requisitos criativos do usuário. Não faça o agente externo ler o README do Summon CLI, SKILL.md, instruções de configuração, configurações públicas, testes ou histórico do Git, nem escreva "explore o projeto e encontre materiais" na transição. Apenas se o usuário nesta rodada solicitar explicitamente que o agente externo revise ou modifique um projeto específico é que ele poderá verificar os arquivos diretamente relacionados à tarefa dentro desse projeto.

As instruções de transição informam apenas qual camada continuará a descoberta de materiais públicos, sem declarar que a preparação final dos materiais foi concluída. Elas servem apenas para o agente externo decidir se continua a usar ferramentas de pesquisa na web, sem entrar nos materiais de trabalho da Skill de destino, nos resultados de preparação da escrita ou no produto final. O processo de análise do Codex, rascunhos com falha, histórico de correções, decisões internas de rota, instruções de manutenção, verificação de fatos, esboços e texto pré-escrito permanecem na tarefa atual.

A entrada completa é passada via stdin para o iniciador:

$input | & '<Diretório desta Skill>\scripts\summon.ps1' run --task writing --skill content-writing --cwd '<Diretório da tarefa atual>'

No macOS, Linux ou WSL, use o summon.sh correspondente. --cwd é o diretório do projeto que o agente externo realmente abrirá; se não for passado, usa o diretório atual de onde o Summon CLI foi chamado, portanto não fica fixo em uma pasta específica da máquina do desenvolvedor.

O summon.py analisa um único profile a partir da configuração local, carrega o ambiente de API correspondente, passa explicitamente o nome da única Skill de destino e o caminho absoluto do SKILL.md para o agente externo, e então inicia o processo usando o protocolo configurado para o modo atual do CLI. Ele não interpreta, resume ou reescreve a entrada.

O modo de execução padrão é visible. O executor claude-code inicia a interface interativa real do Claude Code no Windows Terminal, macOS Terminal.app ou em um terminal gráfico descoberto no Linux, sem usar -p, e começa no modo de permissão Auto; quando a primeira rodada é concluída, o Hook de Parada (Stop Hook) a nível de sessão retorna a resposta completa do Claude para a tarefa atual do Codex, e a janela do Claude permanece aberta no campo de entrada, permitindo que o usuário faça perguntas adicionais ou a feche manualmente. A entrega completa solicitada pelo usuário nesta rodada deve estar na última resposta do agente externo; se o usuário pediu explicitamente uma confirmação por fases, apenas a fase atual é entregue, sem executar as fases seguintes antecipadamente. Se o agente externo, após o resultado completo, enviar um breve resumo de conclusão, o Stop Hook recupera o resultado completo anterior do histórico da sessão atual. Antes de iniciar, as configurações existentes do usuário do Claude Code são mantidas, e a inicialização inicial e o estado de confiança do diretório de trabalho atual são preparados, de modo que a interface não pare na tela de estilo, instruções de segurança ou confirmação de diretório. Em máquinas sem desktop gráfico, é relatado claramente que o modo visível não está disponível, sem alterar para background automaticamente. Tarefas ou profiles na configuração podem definir run_mode como background, caso em que -p é usado para executar em segundo plano e capturar o resultado. Em chamadas explícitas, também é possível usar --run-mode para substituir temporariamente. A ordem de resolução é: comando atual, configuração da tarefa, configuração do profile, valor padrão global.

Em chamadas explícitas, --profile pode ser usado para ignorar o profile padrão da tarefa, e --skill pode substituir a Skill padrão da tarefa. A substituição vale apenas para esta chamada, sem modificar a configuração de longo prazo.

Quando o CLI externo retorna um resultado de sucesso, o resultado completo é entregue. Em caso de falha, o código de saída real, a saída padrão e a saída de erro são retornados; o agente, API ou Skill não são trocados, e o Codex não gera um resultado substituto.

Recursos

• scripts/summon.py: Programa principal multiplataforma, lê a configuração, analisa a tarefa e a única Skill, carrega o ambiente do profile e inicia o CLI do agente externo.
• scripts/summon.ps1, scripts/summon.sh: Pontos de entrada portáteis para Windows e macOS/Linux/WSL, respectivamente.
• config/config.json: Protocolo de execução público, profiles, tarefas e nomes de Skills que podem ser migrados junto com a Skill; não armazena caminhos absolutos da máquina local.
• config/config.local.json: Gerado pelo setup com os caminhos do CLI, Skill e terminal da máquina local; o arquivo está dentro desta Skill e é excluído pelo .gitignore.
• config/profiles/*.env: Ambiente de API para o profile correspondente; o arquivo fica junto com as outras configurações dentro desta Skill e é excluído pelo .gitignore.
• references/configuration.md: Explica como configurar e adicionar novos executores, profiles, tarefas e Skills.

Saída e Conclusão

Por padrão, a interface interativa real ou o processo de execução em tempo real do agente externo é exibido em uma janela separada, e o texto completo ou resultado é retornado para a tarefa atual do Codex, sem qualquer versão adicional do Codex. O retorno do resultado não espera o fechamento da janela; a janela de interação nativa permanece após a primeira rodada, permitindo que o usuário a visualize e faça perguntas adicionais. Quando o agente externo gera arquivos a pedido do usuário, esses arquivos pertencem ao projeto de destino explicitamente especificado pelo usuário; arquivos temporários usados pelo modo visível para a primeira transição são limpos imediatamente após o retorno do resultado, e o iniciador não salva prompts, textos ou logs de execução. O Claude Code, por sua vez, ainda mantém sessões de interação recuperáveis conforme seu mecanismo normal.

Somente quando o agente externo realmente retorna um resultado de sucesso é que a delegação é considerada concluída. A capacidade de analisar a configuração, a existência do arquivo executável e a capacidade de iniciar o comando provam apenas os respectivos níveis; quando faltam chaves de API, a Skill de destino ou um protocolo não interativo compatível, o item ausente é descrito com precisão e a execução é interrompida.