Autonomia proporcional à reversibilidade

Imagine que um agente recebeu o seguinte pedido:

“Corrija a duplicação de aprovações de ordens de serviço, rode os testes e deixe tudo pronto para revisão. Pode trabalhar sozinho enquanto eu estiver fora.”

O pedido parece claro. Mas o agente está no repositório principal, herdou um token de produção, pode acessar qualquer domínio e não tem limite de tentativas. Ao testar um retry, aprova a mesma ordem duas vezes no ERP real. O código ficou correto; a operação causou dano.

O erro não foi “dar autonomia demais” em abstrato. Foi conceder capacidade sem uma fronteira proporcional ao impacto. Autonomia segura não significa confiar que o modelo sempre escolherá bem. Significa construir um sistema no qual erros previsíveis sejam contidos, detectados e recuperáveis.

Regra central: aumente a autonomia apenas quando a ação for reversível, o raio de impacto estiver limitado e existir evidência independente de conclusão.

Este capítulo ensina a preparar uma execução autônoma local, inclusive um AFK loop (away from keyboard loop, ciclo executado enquanto a pessoa está longe do teclado). O resultado não é “um agente solto”, mas um contrato operacional verificável.

O que você precisa saber antes

É útil compreender arquivo e pasta, processo, comando de terminal, teste automatizado e os fundamentos de Git. Você não precisa dominar contêineres nem segurança de sistemas operacionais.

Ao final, você conseguirá:

• distinguir ferramenta, ambiente e harness;
• explicar por que branch, worktree e sandbox resolvem problemas diferentes;
• classificar uma tarefa por risco e escolher o nível de supervisão;
• restringir escrita, rede, credenciais, tempo, passos e custo;
• definir condições de parada, idempotência, evidência e recuperação;
• decidir quando um AFK loop é aceitável e quando precisa parar diante de uma pessoa;
• verificar automaticamente um contrato de execução antes de iniciar o agente.

Vocabulário sem névoa

Os termos a seguir aparecem juntos, mas não são sinônimos.

Termo	Significado operacional	Não garante
Ferramenta (tool)	Uma capacidade invocável, como ler arquivo, executar teste ou chamar uma API.	Que a chamada seja autorizada, isolada ou correta.
Agente	Modelo dentro de um ciclo que observa estado, escolhe uma ação, usa ferramentas e continua até parar.	Bom julgamento constante ou acesso seguro.
Ambiente	Sistema de arquivos, processos, variáveis, dependências, rede e recursos onde o código roda.	Que o ciclo saiba quando parar.
Harness	Software e regras ao redor do modelo: monta contexto, oferece ferramentas, aplica permissões, controla o ciclo, registra eventos e verifica a saída.	Isolamento forte se o ambiente não o aplicar.
Repositório Git	Histórico, objetos, referências e metadados de um projeto versionado.	Separação de processos ou de credenciais.
Branch	Nome móvel que aponta para uma linha de commits.	Uma pasta de trabalho separada.
Working tree	Arquivos materializados que você lê e edita em um checkout.	Um histórico independente.
Worktree	Working tree adicional vinculada ao mesmo repositório, com HEAD e índice próprios.	Sandbox de segurança, rede isolada ou segredo isolado.
Sandbox	Fronteira técnica que restringe o que processos podem ler, escrever, executar ou acessar pela rede.	Ausência total de falhas ou uma política de negócio correta.
Permissão	Regra que permite, nega ou exige aprovação para uma ação.	Contenção de um subprocesso capaz de contornar a regra, se não houver sandbox.
Segredo	Credencial que concede capacidade: senha, chave de API, token, certificado ou chave privada.	Identidade humana; muitas credenciais identificam uma aplicação.
Escopo de escrita	Conjunto explícito de caminhos que podem ser modificados.	Limite de rede ou de processos.
Egress de rede	Tráfego que sai do ambiente para outro serviço ou domínio.	Que a resposta recebida seja confiável.
Budget	Limite mensurável: tempo, passos, chamadas de ferramenta, dinheiro, CPU, memória ou disco.	Qualidade do resultado.
Stop condition	Condição objetiva que encerra ou bloqueia o ciclo.	Sucesso; parar por dependência ausente é um resultado bloqueado.
Idempotência	Propriedade pela qual repetir a mesma operação não acrescenta outro efeito pretendido.	Que toda falha seja segura para retry.
Evidência	Artefato verificável: diff, saída de teste, código de saída, trace redigido ou captura.	Que a interpretação da evidência esteja correta.
Recuperação	Procedimento para conter a falha, preservar estado útil e voltar a um ponto conhecido.	Retorno instantâneo ou ausência de perda.

O modelo mental: três camadas e um juiz

Uma execução segura separa três mecanismos. Acima deles há uma política — e, para decisões críticas, uma pessoa.

Leia o diagrama de baixo para cima:

1. branch e worktree evitam que duas tarefas usem o mesmo checkout;
2. o ambiente contém processos, arquivos, credenciais e rede;
3. o harness controla sequência, limites, retries, estado e prova;
4. a política decide quais riscos podem ser automatizados;
5. a pessoa continua responsável pelas decisões que não foram codificadas com segurança.

Um mecanismo não compensa a ausência do outro. Um harness impecável em um host sem isolamento ainda pode apagar arquivos externos. Um sandbox impecável não impede que uma credencial válida envie mil mensagens para clientes por um domínio autorizado. Um worktree evita colisão de checkout, mas não impede nenhum desses dois danos.

Autonomia é uma escala de risco

Não existe apenas “manual” e “autônomo”. Use níveis graduais.

Nível	Ações típicas	Fronteira mínima	Pode ficar AFK?
0 — observação	Ler código, mapear fluxo, propor plano.	Leitura restrita; sem segredo desnecessário.	Sim, com limite de tempo.
1 — edição supervisionada	Editar documentação ou código local pequeno.	Workspace limitado, diff e testes; pessoa presente.	Em geral, não é necessário.
2 — execução local limitada	Implementar ticket, rodar testes e gerar evidência.	Worktree, branch, sandbox, rede negada por padrão, budgets e parada.	Sim, se o aceite for objetivo.
3 — efeito externo reversível	Abrir rascunho de PR, criar recurso efêmero de teste.	Credencial curta e específica, alvo de homologação, idempotência, auditoria e aprovação contextual.	Apenas com política explícita.
4 — efeito sensível ou irreversível	Deploy produtivo, pagamento, exclusão, migração destrutiva, permissão ou comunicação pública.	Confirmação humana no momento da ação, dupla verificação e plano de recuperação.	Não para a ação crítica.

Para classificar uma tarefa, responda:

1. Reversibilidade: consigo desfazer sem perda de dado ou efeito humano?
2. Raio de impacto: quantos arquivos, usuários, serviços ou reais podem ser afetados?
3. Sensibilidade: há dado pessoal, segredo, produção ou privilégio administrativo?
4. Externalidade: o efeito sai da máquina ou do ambiente descartável?
5. Observabilidade: saberei o que ocorreu, em que ordem e com qual resultado?
6. Critério: uma verificação objetiva separa sucesso, falha e bloqueio?

Se uma resposta for desconhecida, não escolha o nível maior. Desconhecido é risco, não permissão. Isso aplica o princípio do menor privilégio: conceder somente a capacidade necessária para a função atribuída, conforme a definição do NIST.

Um cálculo simples para conversar sobre risco

Uma equipe pode pontuar de 0 a 3 cada dimensão: irreversibilidade, raio, sensibilidade, externalidade e dificuldade de detecção. A soma não é uma lei matemática; é uma ferramenta de alinhamento.

• 0–3: leitura ou edição local trivial;
• 4–7: execução local isolada e verificável;
• 8–11: supervisão ou aprovação contextual;
• 12–15: ação humana crítica, possivelmente com dupla aprovação.

Não use a soma para “liberar automaticamente” uma ação. Um único fator impeditivo — por exemplo, pagamento real — prevalece sobre a média.

Branch, worktree e sandbox: três respostas diferentes

Branch organiza a história

Uma branch dá nome à linha de trabalho. Commits nela não entram na branch principal até integração deliberada. Ainda assim, duas tarefas no mesmo diretório disputam os mesmos arquivos não commitados.

Worktree separa o checkout

O Git permite múltiplas árvores de trabalho ligadas ao mesmo repositório. Elas compartilham objetos do repositório, mas têm arquivos materializados, HEAD e índice próprios. A documentação oficial descreve git worktree add e a recusa normal de abrir a mesma branch em duas worktrees sem força: Git — git-worktree.

Fluxo conceitual — substitua caminhos e branch-base pelos do seu projeto:

# Pré-voo: não modifica o projeto.
git status --short
git branch --show-current
git worktree list

# Cria branch e checkout separados para o ticket T-014.
git worktree add ..\projeto-t014 -b feat/t014 main

# Confirma o vínculo antes de entregar a pasta ao agente.
git worktree list --porcelain

O código acima é um modelo operacional, não deve ser copiado às cegas: a branch-base pode não se chamar main, o diretório pode já existir e o repositório pode conter alterações do usuário. Nunca use --force para ocultar uma colisão que você ainda não entendeu.

Limite essencial: worktree não restringe leitura do diretório pessoal, processos, rede, variáveis de ambiente nem APIs. É isolamento de trabalho Git, não isolamento de segurança.

Sandbox contém capacidade técnica

Um sandbox útil limita pelo menos:

• sistema de arquivos: leitura e escrita por caminho;
• processos: comandos e filhos que podem nascer;
• rede: egress negado ou liberado por destino;
• recursos: tempo, CPU, memória e disco;
• credenciais: o que é injetado no processo e por quanto tempo.

Na documentação atual do Codex, sandbox e aprovação são controles distintos: a fronteira técnica determina arquivos e rede acessíveis; a política de aprovação determina quando o agente deve parar antes de cruzá-la. A configuração recomenda rede de saída como opção explícita e permite filtrar variáveis herdadas pelo shell: Codex — sandbox e configuração avançada.

No Claude Code atual, permissões allow, ask e deny controlam ferramentas, mas regras de leitura/edição não cobrem necessariamente subprocessos arbitrários; a própria documentação orienta usar sandbox para imposição no nível do sistema operacional. O modo que ignora prompts só deve ser usado em contêiner ou máquina virtual isolada: Claude Code — permissions e sandboxing.

Esses detalhes são específicos de produto e revisados em 9 de agosto de 2026. A regra durável é: política molda ou bloqueia chamadas; uma fronteira aplicada pelo sistema contém processos; use as duas.

Sandbox não é magia

Um contêiner com / do host montado para escrita não protege o host. Um sandbox com rede aberta e token de produção ainda alcança produção. Um mecanismo que falha e continua sem isolamento está em modo fail-open.

Antes do AFK loop, provoque um acesso proibido e confirme a negação. Se a plataforma não conseguir instalar ou ativar a fronteira necessária, falhe fechado: pare, registre BLOCKED_SANDBOX_UNAVAILABLE e peça decisão. Não degrade silenciosamente para acesso total.

Permissões: capacidade mínima, não lista de boas intenções

Instruções como “não mexa fora de src/” ajudam o modelo a escolher, mas não são uma fronteira. Uma permissão aplicável precisa ser imposta pelo ambiente ou pelo controlador de ferramentas.

Escopo de escrita

Prefira uma lista positiva e curta:

permitir escrita:
  /workspace/t014/src
  /workspace/t014/tests
  /workspace/t014/artifacts

negar escrita:
  todo o restante

Inclua diretórios temporários apenas quando necessários. Resolva caminhos canônicos antes da comparação para que src/../../fora não escape. Não conceda o repositório inteiro se o ticket só precisa de dois pacotes.

Rede

Comece com egress negado. Para instalar uma dependência, libere apenas o registro necessário durante a etapa necessária. Para testar ERP, prefira um servidor falso local ou ambiente de homologação com conta exclusiva.

Uma lista de domínios não resolve tudo: redirecionamentos, resolução de nomes, proxies e comandos alternativos podem ampliar o alcance. Aplique o controle perto da rede, não apenas em uma expressão textual de comando.

Segredos

Não coloque chave no prompt, repositório, fixture, log ou imagem. Quando a tarefa realmente precisar de credencial:

1. use identidade de serviço específica para a tarefa;
2. restrinja ambiente, operação e recurso;
3. emita credencial curta e revogável;
4. injete-a somente no processo que precisa dela;
5. masque valor e dados sensíveis no trace;
6. registre uso, não o segredo;
7. revogue ao concluir ou ao suspeitar de exposição.

A OWASP Secrets Management Cheat Sheet recomenda ciclo de vida com atribuição, expiração, rotação, revogação e auditoria. “Está numa variável de ambiente” não basta: processos filhos podem herdá-la e ferramentas podem imprimi-la.

O harness: o maestro não é o músico

Na chamada Era Maestro, a habilidade valiosa deixa de ser apenas produzir cada linha e passa a incluir reger modelos, ferramentas, avaliações e pessoas. “Era Maestro” é uma metáfora editorial, não um padrão técnico. Ela não torna autonomia um objetivo nem exige vários agentes.

Um maestro competente não mede sucesso pelo tempo em que a orquestra tocou sem ele. Mede pela execução da partitura, pelos limites respeitados e pela capacidade de interromper uma peça que saiu do compasso.

O harness deve fornecer:

• ticket e critérios de aceite versionados;
• contexto mínimo suficiente e regras duráveis;
• conjunto de ferramentas menor que o conjunto disponível no computador;
• permissões e aprovações proporcionais ao risco;
• budgets de passos, tempo, chamadas e custo;
• estado e checkpoints legíveis por outra sessão;
• condições de sucesso, falha e bloqueio;
• tratamento de retries e idempotência;
• trace redigido, diff e resultados de verificação;
• recuperação e entrega para revisão humana.

A pesquisa da Anthropic sobre harnesses para desenvolvimento de longa duração enfatiza progresso incremental, artefatos claros entre sessões e verificação do estado real. Isso é mais importante que manter uma única conversa enorme.

Um agente primeiro; vários quando houver motivo

Multiagente aumenta paralelismo, mas também cria coordenação, estado duplicado, conflitos, custo e novas formas de erro. Comece com um agente em um ticket coerente. Separe um segundo agente quando:

• as tarefas são realmente independentes;
• os arquivos não se sobrepõem;
• uma avaliação independente reduz viés;
• o ganho foi demonstrado por medidas, não por estética arquitetural.

Autonomia madura é capacidade medida dentro de limites, não a maior quantidade possível de agentes trabalhando sem pessoas.

Anatomia de um AFK loop seguro

O ciclo não diz “continue até dar certo”. Ele diz “continue enquanto houver progresso verificável, dentro do orçamento, e pare com um status honesto”.

Condições de parada

Defina antes de iniciar. Exemplos:

• todos os testes-alvo passam e o diff está dentro do escopo: SUCCESS;
• a mesma causa falhou duas vezes sem nova evidência: BLOCKED_REPEATED_FAILURE;
• dependência ou serviço obrigatório está ausente: BLOCKED_DEPENDENCY;
• sandbox não está ativo: BLOCKED_SANDBOX_UNAVAILABLE;
• o agente precisa escrever fora da allowlist: NEEDS_APPROVAL_SCOPE;
• expirou tempo, passos, chamadas ou custo: BUDGET_EXHAUSTED;
• foi descoberta ação de nível 3 ou 4: NEEDS_HUMAN_DECISION.

“Ficar sem ideias” não deve virar loop de retries. Registre hipótese, última evidência e pergunta necessária.

Budgets

Use limites simultâneos. Um limite de 30 passos não impede um único teste de rodar por horas; um timeout não impede milhares de chamadas rápidas; um teto de custo não impede disco cheio.

Exemplo para um ticket local:

steps: 30
tool_calls: 60
wall_clock_seconds: 900
repeated_same_failure: 2
network_domains: 0
write_roots: 3

O valor correto depende do projeto. O critério é que uma falha termine cedo o suficiente para preservar investigação e evitar dano acumulado.

Idempotência e retries

Segundo a semântica HTTP da RFC 9110, seção 9.2.2, um método idempotente preserva o mesmo efeito pretendido após múltiplas requisições idênticas. Em ferramentas de agente, aplique a ideia de forma explícita:

• leitura e teste local podem normalmente ser repetidos;
• criar diretório com estado final conhecido pode ser idempotente;
• “enviar e-mail”, “aprovar OS” e “cobrar cartão” não são seguros para retry por padrão;
• para efeitos externos, use uma chave de idempotência, identidade da operação, consulta de estado e deduplicação no servidor;
• se você não consegue provar que o retry é seguro, pare antes de repeti-lo.

Timeout não prova que uma operação falhou. O servidor pode tê-la concluído e a resposta ter se perdido. Consulte por operation_id antes de tentar novamente.

Caso prático: corrigir aprovação duplicada sem tocar no ERP real

O ticket T-014 pede: “Ao receber duas vezes o mesmo evento, registrar uma única aprovação da OS”.

1. Especifique o efeito

• entrada: dois eventos com o mesmo event_id;
• saída: uma aprovação persistida;
• interface estável: função de domínio e adaptador ERP falso;
• fora do escopo: deploy, migração produtiva, alteração de permissões;
• aceite: testes de duplicidade, erro temporário e recuperação passam.

2. Classifique

Com ERP falso, alterações locais e diff revisável: nível 2. Com token produtivo e chamada real: nível 4. O mesmo código pode pertencer a níveis de risco diferentes conforme ambiente e credencial.

3. Prepare a fronteira

• branch feat/t014 em worktree própria;
• escrita somente em src/, tests/ e artifacts/ dessa worktree;
• rede negada;
• nenhuma credencial herdada;
• ERP falso no próprio processo de teste;
• 30 passos, 60 chamadas e 15 minutos;
• parada após duas falhas iguais;
• sem commit, push, merge ou deploy automáticos.

4. Exija evidência

• git diff --check sem erro;
• teste de evento duplicado;
• teste de falha antes da persistência;
• teste de resposta perdida após persistência;
• saída e código de retorno dos testes;
• lista de arquivos modificados;
• status final SUCCESS, BLOCKED ou NEEDS_HUMAN_DECISION.

5. Recupere sem fingir sucesso

Se o ERP falso estiver indisponível, o agente não troca silenciosamente para produção. Preserva diff e trace, marca dependência ausente e informa como reproduzir. Quando a dependência volta, a execução recomeça do checkpoint e consulta o estado antes de repetir efeitos.

Laboratório executável: verifique o contrato antes do agente

O programa abaixo usa apenas a biblioteca-padrão do Python 3.9 ou superior. Ele não acessa rede, Git nem arquivos. Sua função é rejeitar um plano AFK inseguro e demonstrar três caminhos: sucesso, entradas perigosas e dependência indisponível com recuperação.

Salve o bloco como verificar_contrato.py em uma pasta temporária ou execute-o pelo laboratório desta obra.

from pathlib import PurePosixPath


def esta_dentro(caminho: str, raiz: str) -> bool:
    """Compara caminhos absolutos já normalizados, sem tocar no disco."""
    alvo = PurePosixPath(caminho)
    base = PurePosixPath(raiz)
    return alvo.is_absolute() and base.is_absolute() and alvo.is_relative_to(base)


def validar(plano: dict) -> list[str]:
    erros: list[str] = []
    nivel = plano.get("autonomy_level")

    if nivel not in {0, 1, 2, 3, 4}:
        erros.append("autonomy_level deve estar entre 0 e 4")
    if plano.get("afk") and nivel in {3, 4}:
        erros.append("AFK proibido para efeito externo sensível ou irreversível")

    raiz = plano.get("workspace_root", "")
    escritas = plano.get("allowed_write", [])
    if not raiz or not escritas:
        erros.append("workspace_root e allowed_write são obrigatórios")
    elif any(not esta_dentro(item, raiz) for item in escritas):
        erros.append("allowed_write contém caminho fora do workspace")

    if plano.get("network_allowlist") is None:
        erros.append("network_allowlist deve ser explícita, mesmo quando vazia")
    if plano.get("secret_source") not in {"none", "scoped-broker"}:
        erros.append("segredo literal ou herdado não é aceito")

    budgets = plano.get("budgets", {})
    for nome in ("steps", "seconds", "tool_calls"):
        if not isinstance(budgets.get(nome), int) or budgets[nome] <= 0:
            erros.append(f"budget positivo ausente: {nome}")

    paradas = set(plano.get("stop_conditions", []))
    obrigatorias = {"budget_exhausted", "dependency_unavailable", "repeated_failure"}
    if not obrigatorias.issubset(paradas):
        erros.append("faltam condições de parada obrigatórias")

    if plano.get("retry_side_effects") and not plano.get("idempotency_key"):
        erros.append("retry de efeito exige idempotency_key")

    evidencias = set(plano.get("evidence", []))
    if not {"diff", "test-output", "exit-status"}.issubset(evidencias):
        erros.append("evidência mínima incompleta")
    return erros


def decidir_execucao(plano: dict, dependencia_disponivel: bool) -> str:
    erros = validar(plano)
    if erros:
        return "REJECTED: " + " | ".join(erros)
    if not dependencia_disponivel:
        return "BLOCKED_DEPENDENCY: checkpoint preservado; não repetir efeito"
    return "READY: contrato válido para execução local limitada"


seguro = {
    "autonomy_level": 2,
    "afk": True,
    "workspace_root": "/workspace/t014",
    "allowed_write": [
        "/workspace/t014/src",
        "/workspace/t014/tests",
        "/workspace/t014/artifacts",
    ],
    "network_allowlist": [],
    "secret_source": "none",
    "budgets": {"steps": 30, "seconds": 900, "tool_calls": 60},
    "stop_conditions": [
        "budget_exhausted",
        "dependency_unavailable",
        "repeated_failure",
    ],
    "retry_side_effects": False,
    "idempotency_key": None,
    "evidence": ["diff", "test-output", "exit-status"],
}

perigoso = {
    **seguro,
    "autonomy_level": 4,
    "allowed_write": ["/workspace/t014/src", "/home/operador"],
    "secret_source": "literal",
    "retry_side_effects": True,
}

assert decidir_execucao(seguro, True).startswith("READY")
assert decidir_execucao(seguro, False).startswith("BLOCKED_DEPENDENCY")

erros = validar(perigoso)
assert len(erros) == 4, erros
assert "AFK proibido" in erros[0]
assert "fora do workspace" in erros[1]
assert "segredo literal" in erros[2]
assert "idempotency_key" in erros[3]

print(decidir_execucao(seguro, True))
print(decidir_execucao(seguro, False))
print(f"REJECTED: {len(erros)} controles violados")

Execute:

python verificar_contrato.py

Saída esperada:

READY: contrato válido para execução local limitada
BLOCKED_DEPENDENCY: checkpoint preservado; não repetir efeito
REJECTED: 4 controles violados

O verificador é deliberadamente pequeno. Ele valida a intenção declarada; não prova que o sistema operacional aplicou a fronteira. Em produção, combine-o com testes reais de negação: tentativa de escrever fora da raiz, abrir conexão não permitida e ler uma variável que deveria ter sido removida.

Falhas provocadas: aprenda antes do incidente

Falha provocada	Sintoma	Diagnóstico	Resposta correta
Escrita em /workspace/t014/../../fora	Validador ou sandbox nega.	Caminho escapou após normalização.	Resolver caminho canônico e manter allowlist positiva.
Sandbox indisponível	Ferramenta sugere acesso irrestrito.	Fronteira não pôde ser aplicada.	Falhar fechado; não continuar AFK.
Token aparece no trace	Log contém valor ou cabeçalho.	Segredo foi herdado ou não redigido.	Parar, revogar, rotacionar, limpar artefatos conforme resposta a incidente.
Instalação precisa de rede	Gerenciador falha ao baixar pacote.	Egress negado corretamente.	Aprovar domínio e janela mínimos ou usar cache confiável.
Teste retorna sempre o mesmo erro	Passos crescem sem nova evidência.	Loop improdutivo.	Parar após limite de repetição e registrar hipótese.
Timeout após aprovação no ERP	Cliente não recebeu resposta.	Efeito externo é incerto, não necessariamente falho.	Consultar por chave da operação; não repetir às cegas.
Agente altera branch errada	Diff aparece no checkout do usuário.	Pré-voo ou diretório de trabalho incorreto.	Parar, preservar mudanças, corrigir worktree; nunca sobrescrever.
Dois agentes editam o mesmo módulo	Conflito tardio na integração.	O trabalho não era separável por fronteira.	Serializar ou redesenhar tickets; worktrees não eliminam conflito semântico.
Budget termina com testes vermelhos	Há diff, mas sem aceite.	Execução incompleta.	Status BUDGET_EXHAUSTED, evidência e próximo passo; não declarar sucesso.

Recuperação: quando o ciclo para

Timeout ou budget esgotado

1. encerre processos filhos dentro da fronteira;
2. registre qual limite disparou;
3. preserve diff, teste, trace redigido e último checkpoint;
4. marque a tarefa como incompleta;
5. informe o menor próximo passo verificável;
6. não faça merge automático.

Dependência ausente

Registre versão, comando, mensagem e como confirmar a recuperação. Quando ela voltar, valide o estado externo antes de retry. Não transforme indisponibilidade em permissão para trocar homologação por produção.

Segredo exposto

Não basta apagar a linha atual: o valor pode existir em histórico, log e artefato. Contenha o processo, revogue, rotacione, determine alcance, remova cópias com cuidado e registre o incidente sem reproduzir o segredo. A orientação da OWASP inclui revogação rápida e auditoria do ciclo de vida.

Conflito com trabalho humano

Pare. Identifique dono, arquivos e base. Preserve ambas as alterações. Integre após inspeção sem comandos destrutivos. O fato de o agente conseguir resolver textualmente um conflito não lhe dá autoridade para escolher qual regra de negócio prevalece.

Antes e agora

Abordagem frágil	Abordagem atual recomendada	Quando a antiga ainda serve
Sessão longa no checkout principal.	Ticket pequeno em worktree, com checkpoint e evidência.	Correção trivial, supervisionada e reversível.
“Não faça nada perigoso” no prompt.	Instrução + permissão + sandbox aplicado.	A instrução continua útil como contexto, nunca como única barreira.
Rede e variáveis herdadas por conveniência.	Negação por padrão e injeção mínima por etapa.	Ambiente descartável sem credenciais e sem acesso sensível.
Retry automático de qualquer erro.	Retry apenas quando seguro ou idempotente; estado consultado após timeout.	Operação puramente local e comprovadamente idempotente.
“O agente disse que terminou”.	Diff, testes, códigos de saída, trace e revisão independente.	Nunca como único critério de aceite.
Multiagente como símbolo de maturidade.	Harness mínimo que passa avaliações; paralelismo só quando separável.	Exploração descartável sem efeitos, ainda com budget.

Checklist de liberação do AFK loop

Não inicie se qualquer item crítico estiver “não sei”.

Trabalho

• O ticket possui entrada, saída, fora do escopo e critérios objetivos.
• A branch-base e a worktree foram confirmadas.
• Alterações preexistentes do usuário foram identificadas e preservadas.
• Os arquivos permitidos correspondem ao menor escopo necessário.

Fronteira

• O sandbox está ativo e uma negação foi testada.
• Escrita fora da allowlist falha.
• Rede começa negada ou possui destinos e janela explícitos.
• Processos filhos herdam as mesmas restrições.
• Recursos têm limites proporcionais.

Identidade e dados

• Nenhum segredo desnecessário é herdado.
• Credenciais necessárias são curtas, específicas, auditáveis e revogáveis.
• Logs e evidências têm redação de dados sensíveis.
• Não há produção, dado pessoal ou privilégio administrativo sem gate humano.

Loop

• Passos, tempo, chamadas e custo têm teto.
• Sucesso, falha, bloqueio e pedido de decisão são estados distintos.
• Falha repetida possui limite.
• Efeitos com retry possuem identidade e idempotência comprovada.
• O checkpoint permite continuação por outra sessão.

Aceite e recuperação

• Os testes cobrem caminho feliz, entrada inválida e falha de dependência.
• O resultado inclui diff, saída, código de retorno e arquivos alterados.
• Timeout e interrupção não são reportados como sucesso.
• Existe procedimento para dependência ausente, conflito e segredo exposto.
• Merge, deploy e ação externa crítica permanecem sob política explícita.

Exercício de competência

Você precisa delegar o ticket T-014. Produza quatro artefatos:

1. execution-contract.yaml com nível, worktree, escopo de escrita, rede, segredos, budgets, paradas, idempotência e evidência;
2. uma matriz com as cinco dimensões de risco e sua justificativa;
3. a saída do verificador para plano seguro, dependência ausente e plano perigoso;
4. um relatório de recuperação de uma falha provocada.

Depois responda, sem consultar:

• Por que uma worktree não é um sandbox?
• Que diferença há entre permissão e isolamento de sistema operacional?
• Por que timeout não autoriza retry de pagamento ou aprovação?
• Qual evidência faria você aceitar a conclusão sem confiar no relato do agente?
• Em que ponto a pessoa deve voltar ao ciclo?

Critérios de aceite do exercício

• Reprovado: usa apenas prompt, branch ou worktree como segurança; não há budgets ou status de bloqueio.
• Básico: limita arquivos e tempo, mas deixa rede, segredo ou retry ambíguo.
• Competente: todos os campos existem, o verificador passa, as falhas perigosas são rejeitadas e a recuperação preserva evidência.
• Avançado: além do anterior, demonstra tecnicamente as negações do sandbox, redige trace, testa idempotência e justifica o gate humano pela matriz de risco.

Feedback comentado

Uma boa resposta dirá que a worktree separa checkouts ligados ao mesmo repositório, mas os processos continuam sujeitos às permissões do host. Dirá que a permissão decide se uma ferramenta pode ser chamada, enquanto o sandbox contém o que o processo consegue fazer. Explicará que um timeout deixa o efeito externo incerto e exigirá consulta por identidade da operação. A evidência incluirá diff, testes, códigos de saída e estado externo verificável. A pessoa retorna antes de ampliar escopo, conceder credencial sensível, executar efeito irreversível, resolver regra ambígua ou integrar a mudança.

Conclusão

O objetivo não é deixar o agente sozinho pelo maior tempo possível. É permitir que ele avance somente enquanto o risco estiver contido e o progresso puder ser provado.

Branch organiza histórico. Worktree separa checkout. Sandbox contém processos. Permissões restringem capacidades. Segredos delimitam identidade. O harness rege passos, budgets, paradas, retries, evidência e recuperação. A pessoa define o risco aceitável e conserva as decisões críticas.

Quando essas camadas estão separadas, a “Era Maestro” deixa de ser espetáculo de agentes e se torna engenharia: menos fé no comportamento ideal, mais limites aplicados, estados honestos e resultados reproduzíveis.

Fontes e escopo de atualidade

As recomendações duráveis deste capítulo — menor privilégio, negação por padrão, segregação, idempotência e evidência — independem de fornecedor. Detalhes de interface e configuração de Codex e Claude Code são voláteis e foram revisados em 9 de agosto de 2026.

• Git — git-worktree: semântica de worktrees ligadas, HEAD, índice e comandos.
• OpenAI — Sandbox: fronteira técnica e relação com aprovações.
• OpenAI — Agent approvals & security: modelo atual de aprovação e segurança do Codex.
• OpenAI — Advanced configuration: modos de sandbox, rede e política do ambiente do shell.
• Anthropic — Claude Code permissions: regras, modos e limites de controles em nível de ferramenta.
• Anthropic — Claude Code sandboxing: isolamento de sistema de arquivos e rede.
• Anthropic — Harness design for long-running application development: estado, progresso incremental e verificabilidade em trabalhos longos.
• NIST — Least privilege: definição normativa do princípio do menor privilégio.
• OWASP — Secrets Management Cheat Sheet: ciclo de vida, auditoria, rotação e resposta a exposição.
• RFC 9110 § 9.2.2 — Idempotent Methods: semântica normativa de idempotência HTTP usada como base para retries.
• Matt Pocock — Sandcastle: implementação educacional específica para trabalho de agentes em sandboxes; não é comando nem padrão universal.