stop-guard

Extensão do Pi para continuar tarefas autorizadas sem exigir “ok”, “sim” ou “pode seguir” a cada resposta do modelo.

A confirmação de parada é do modelo para o harness, não um popup para você. Ao tentar encerrar sem uma decisão, o Pi recebe uma mensagem interna e faz outra chamada automaticamente. O modelo deve executar o próximo passo ou chamar stop_guard com um motivo:

• finished: trabalho concluído, sem pendências, com evidências.
• ask_user_question / need_user_input: falta uma informação concreta; exige a pergunta exata.
• need_confirmation: falta uma autorização real; exige a pergunta exata.
• blocked: obstáculo externo documentado.
• continue: recusa a parada e manda continuar.

Depois de uma decisão aprovada, o modelo ainda produz a resposta final ou pergunta. Outra ferramenta ou nova mensagem invalida a aprovação. As decisões ficam registradas no histórico como stop-guard-decision.

Instalação

Requer Node >=22.15 e Pi @earendil-works/pi-coding-agent >=1.0.4 <2. O antigo @mariozechner/pi-coding-agent não tem o evento usado aqui e não é suportado por esta versão. As versões atuais das sete extensões também usam o namespace @earendil-works.

Extraia o arquivo de código-fonte, entre na pasta e execute:

npm ci
pi install /caminho/absoluto/stop-guard

Em uma sessão já aberta, execute /reload. Para experimentar sem instalar globalmente:

pi -e /caminho/absoluto/stop-guard/src/index.ts

Uso

Funciona automaticamente nas conversas normais. O padrão permite até 12 retomadas automáticas por entrada. O limite é total, não reinicia só porque o modelo chamou alguma ferramenta. Ao atingir o limite, aparece um aviso explícito de que o trabalho pode estar incompleto.

/stop-guard status
/stop-guard off
/stop-guard on
/stop-guard limit 30
/stop-guard limit 0
/stop-guard reset

limit 0 remove o limite de retomadas do guard (modo YOLO), podendo consumir tokens indefinidamente se o modelo ignorar as instruções. reset zera o contador, mas não inicia uma tarefa sozinho. As opções são locais à sessão e voltam ao padrão ao recarregar ou navegar na árvore. Escape/cancelamento e erros do provedor continuam interrompendo a execução; o guard não substitui permissões do Pi.

Paralelismo

A extensão acrescenta uma instrução para avaliar dependências antes de trabalho substancial, delegar tarefas independentes de forma concorrente usando os recursos instalados e conferir os resultados. A ferramenta de parada exige uma avaliação explícita: used, unnecessary ou unavailable, com justificativa.

Não cria um segundo runtime de subagentes, não inventa parâmetros de subagent e não altera as ferramentas existentes. O modelo deve seguir o schema instalado — versões recentes de pi-subagents têm workflows, não necessariamente o antigo argumento tasks. Tarefas pequenas ou dependentes podem continuar sequenciais. A seleção das tarefas e a veracidade da justificativa ainda dependem do modelo; isto não é um auditor semântico independente.

Compatibilidade

Pacotes reais instalados e carregados simultaneamente nos testes, com o guard antes e depois deles:

Quando pi-goal-x assume um objetivo, ele controla continuidade, pausas e auditoria. O guard mantém a orientação de paralelismo, mas não reinicia o objetivo depois que o controlador para. A posse do loop é mantida até a próxima entrada, inclusive se update_goal desaparecer após a conclusão. Sem objetivo ativo, instalar pi-goal-x não desliga o guard.

/stop-guard owner guard força o guard a controlar também esse cenário. Use somente se o outro controlador estiver desativado; dois controladores autônomos podem interferir entre si. /stop-guard owner auto restaura a integração padrão. A detecção usa o perfil público de ferramentas de pi-goal-x; mudanças futuras desse perfil exigem revalidação.

Se stop_guard for removido da lista de ferramentas ativas por outro pacote, a extensão não exige que o modelo chame uma ferramenta indisponível. Ela não redefine listas de ferramentas, atalhos, widgets de terceiros ou arquivos de configuração.

Testes e limites da validação

npm ci
npm run check
npm test

Os 19 testes passaram no Pi 1.0.4. Os testes exercitam condições de parada, perguntas, orçamento de retomadas, cancelamento/erro, invalidação de aprovações, isolamento entre sessões e encadeamento de prompt. Os testes SDK executam o loop real do Pi com um provedor de respostas programadas: reproduzem a parada prematura, retomam sem entrada humana, escrevem um arquivo pela ferramenta real, aprovam a parada e emitem a resposta final. Também testam os sete pacotes juntos nas duas ordens e a criação real de um objetivo via pi-goal-x.

Não foi usado um LLM externo: o ambiente não fornece credenciais de modelo. Portanto os testes comprovam o mecanismo do harness e os cenários descritos, não garantem que qualquer modelo delegará bem ou declarará conclusão honestamente. As UIs interativas e subprocessos de subagentes com provedores reais ainda precisam de teste na sua instalação. Não há promessa de compatibilidade com todas as versões/configurações possíveis.

A extensão usa agent_before_settle, o ponto em que o Pi já tratou ferramentas e trabalho automático. Injeta uma entrada custom_message oculta e pede continue: true. Não usa timers de retomada, não fabrica “sim” do usuário e não chama a API do provedor por fora do Pi.