Coloque portões nas ferramentas que alteram as coisas

Cerca de 37 minutos min de leitura, com 12 exemplos em 12 seções.

Edição 2026.11.2 Exemplos aprovados em 20 de nov de 2026 64 de 64 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.2. Leia o original

Ao final deste capítulo, você será capaz de manter as alterações de um agente na cópia própria dele até que uma pessoa diga sim, verificar se esse sim cobre exatamente a alteração que ela leu e devolver um não ao agente como motivo para a execução ter parado.

O agente deste livro mantém unitcraft, uma biblioteca cujo mantenedor é dono de cada alteração que entra nela, e trabalha em uma cópia descartável dessa biblioteca. Os testes e as edições dele acontecem na cópia. Ainda assim, é preciso decidir quando uma alteração chega à biblioteca que o mantenedor possui, e, neste caso, o mantenedor é a pessoa que abriu a issue. A tarefa T-04 mostra claramente o que está em jogo. A issue pede uma unidade a mais, a polegada, e a cópia do agente contém uma edição que a adiciona. Se essa edição entra ou não é uma decisão para uma pessoa, e o agente não deve tomá-la por ela.

Este capítulo constrói a parte do harness que pergunta. As ferramentas de arquivo do agente escrevem apenas na cópia da execução, e a biblioteca só muda quando o harness aplica o diff de uma execução depois do sim de uma pessoa. Sobre isso há duas verificações: um portão que lê o diff em finish, e uma guarda que compara os bytes da biblioteca antes e depois de cada chamada de ferramenta. O portão e a guarda são código didático e uma segunda camada, e nenhum dos dois é uma sandbox. A principal defesa para o código que o agente escreve é um contêiner ou uma máquina virtual, que o capítulo 7 explica. Nenhum exemplo aqui executa um, e nenhuma gravação mostra um. Cada chamada de ferramenta é envolvida por uma comparação dos bytes da biblioteca do caso, e a guarda falha de forma fechada: quando a biblioteca tiver mudado, a execução termina como library_changed, o harness não aplica nada e não restaura nada. A primeira seção diz o que a cópia não impede.

A cópia vem primeiro

As ferramentas de arquivo do agente alcançam os arquivos somente por meio da sua cópia. Cada execução recebe a própria cópia, criada por scratch_copy em run_task, e as ferramentas trabalham por meio de um Workspace com raiz nessa cópia. Workspace.locate resolve todo caminho que o modelo fornece. Ele recusa um caminho que seja absoluto, um que tenha uma parte .., um que contenha um byte NUL ou uma barra invertida, um que resolva por um link simbólico para um lugar fora da cópia e qualquer escrita dentro de .github/. Por meio dessas ferramentas, um caminho que não resolve dentro da cópia nunca chega ao disco.

Essas verificações cobrem os caminhos que as ferramentas recebem. Elas não cobrem o código que o agente executa. run_tests executa o pytest sobre a cópia, e o pytest executa tudo o que o modelo escreveu ali. Um módulo de teste que o modelo acrescenta também é código. A execução dos testes importa esse módulo e o executa com os direitos de usuário do harness e sem sandbox, de modo que pode escrever em qualquer caminho que esse usuário possa escrever, inclusive na biblioteca. O executor não carrega arquivos conftest.py (run_pytest passa --noconftest), mas coleta módulos de teste, e essa é a rota de que esta seção trata. O gate não consegue impedir essa escrita, porque ele lê apenas o diff em finish. A proteção da biblioteca, na sua seção, percebe a escrita assim que run_tests retorna, encerra a execução como library_changed e não restaura nada. Ela detecta a escrita depois que ela acontece. Não a impede.

Este é o lado aberto do harness, e é a principal limitação deste capítulo. O Capítulo 7 descreve a sandbox de ensino do livro, que executa os comandos do agente com limites e um ambiente limpo. Sua tabela lista o que ela deixa aberto, e as escritas fora da cópia estão nessa lista. Um contêiner ou uma máquina virtual é a defesa principal para executar código escrito por um modelo, e o Capítulo 7 explica ambos. As verificações deste capítulo são código didático, escrito para que o leitor possa abri-las, copiá-las e testá-las. Elas não substituem esse isolamento.

A biblioteca muda em um único ponto. apply em lib/permissions.py grava bytes novos na biblioteca, e seu único chamador é a resposta do gate a uma proposta, depois de um sim. library_copy cria a biblioteca descartável sobre a qual os exemplos aplicam as mudanças, de modo que a pasta de casos do livro nunca é escrita. Quando uma execução termina, Gate.settle informa o que a cópia ainda contém, e nada da cópia é escrito de volta na biblioteca.

Uma escrita também pode falhar no meio de um apply. O próximo exemplo traz uma proposta com dois arquivos e coloca uma pasta no lugar onde o segundo arquivo vai, de modo que a segunda escrita falha.

apply-all-or-nothing.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""A proposal of two files where the second cannot be written, because a folder stands where it goes. The first fileis put back, the error goes back as the handoff, and the library holds the bytes it held before the finish."""from lib.case import CASEfrom lib.permissions import Gate, answer, gated, library_copyfrom lib.tasks import snapshotfrom lib.tools import V1, Workspacewith library_copy() as library, library_copy() as scratch:    (library / "unitcraft" / "extra.py").mkdir()    before = snapshot(library, ".")    (scratch / "README.md").write_text("A new line in the readme.\n", encoding="utf-8")    (scratch / "unitcraft" / "extra.py").write_text('"""Extra."""\nTOTAL = 1\n', encoding="utf-8")    gate = Gate(library, lambda p: answer(p, True))    result = gated(V1, gate).call(Workspace(scratch), "finish", {"summary": "Two files."})    print("ended:", result.end)    print("handoff:", result.question)    print("README as before:", snapshot(library, "README.md") == snapshot(CASE, "README.md"))    print("library bytes unchanged:", snapshot(library, ".") == before)    print("applied:", gate.counts["applied"], "refused:", gate.counts["refused"])    assert result.end == "ask_user" and "apply failed (IsADirectoryError)" in result.question    assert snapshot(library, ".") == before and gate.counts["applied"] == 0
Saídapython apply-all-or-nothing.py
ended: ask_user
handoff: p-1 was not applied: apply failed (IsADirectoryError); library restored
README as before: True
library bytes unchanged: True
applied: 0 refused: 1

apply restaura cada arquivo que havia tocado e cada pasta que havia criado, e o gate mantém a proposta com o erro como motivo: p-1 was not applied: apply failed (IsADirectoryError); library restored. O README, que foi escrito primeiro, volta ao estado anterior ao finish, e os bytes da biblioteca permanecem inalterados. O gate captura um OSError como proposta retida. Qualquer outra exceção também restaura os arquivos e então é relançada, e nenhum exemplo aqui mostra esse caminho.

Regra prática: Dê a cada execução a sua própria cópia, recuse todo caminho que resolva para fora dela e deixe exatamente uma função escrever no original, chamada somente depois de um sim. Depois, diga o que o código da execução ainda pode fazer ao original, verifique isso com uma proteção e não conte com o gate como proteção.

Em qual modo este harness está

Um gate precisa de resposta para uma pergunta antes de tudo: quem responde quando o agente para para perguntar? O modo interativo do Claude Code pergunta a uma pessoa na sessão. O Claude Agent SDK oferece vários modos de permissão que diferem nesse ponto, e um harness precisa dizer a qual deles se parece, porque a resposta define o que acontece com uma chamada que precisa de aprovação quando ninguém pode responder. Este harness não tem terminal nem sessão. É uma execução headless, e a única parte que pode responder é um callback que o chamador passa.

A documentação do fornecedor separa os casos. A página de permissões do Claude Code diz que as regras são verificadas na ordem deny, ask, allow, e que a primeira correspondência decide o resultado. Diz também que o Claude Code pede confirmação antes de modificar arquivos por padrão, e que o trabalho somente leitura dentro do diretório de trabalho roda sem pedido. A página de permissões do Agent SDK descreve um modo dontAsk, no qual qualquer chamada que, de outro modo, pediria confirmação é negada sem chamar o callback de aprovação. Nenhum dos dois produtos foi executado para este capítulo, então as afirmações sobre eles são do fornecedor e estão marcadas como tal.

Este harness mantém o seu callback. Uma mudança que precisa de um sim chama o aprovador e espera pela resposta. O modo dontAsk do fornecedor difere em um ponto que importa aqui: ele nega essa chamada sem chamar o callback, e este harness sempre a chama. O livro chama isso de execução headless com callback, e não dontAsk. O gate é o mesmo qualquer que seja o adaptador de modelo usado na execução, porque ele envolve as ferramentas e não o modelo. O protocolo do modelo no capítulo 4 é a parte que muda de um modelo para outro.

Regra prática: Diga o modo antes de adicionar um gate. Quando o chamador tem um callback que pode responder, faça o gate chamá-lo e esperar pela resposta. Um gate criado sem aprovador se recusa a iniciar: o código deste capítulo levanta um erro. Um projeto que transfere a decisão quando ninguém pode responder precisa de um caminho próprio, e nenhum exemplo deste capítulo mostra um.

O portão fica em finish

A maior parte do que o agente faz não altera nada que pertença ao mantenedor. Ele lista arquivos, lê-os e executa os testes visíveis. Suas edições na cópia são trabalho próprio dele, e é esperado que sejam feitas. A única chamada que pede uma mudança na biblioteca é finish, por isso a verificação do portão fica ali, e finish é onde uma proposta é feita.

O portão envolve toda ferramenta do conjunto, e a classe de cada ferramenta vem de uma única tabela em lib/permissions.py. As leituras (list_files, read_file, run_tests e ask_user) passam livremente, e a guarda da biblioteca observa cada uma delas. run_tests está na classe de leitura, mas executa código que o modelo escreveu, como diz a seção sobre a cópia. As edições e escritas (edit_file e write_file) são executadas na cópia, e o portão conta cada chamada. finish é uma proposta. Sua classe vem da tabela do arcabouço de execução e de nada que o modelo tenha escrito, de modo que nem o resumo do modelo nem a descrição de uma ferramenta a definem. Os nomes, descrições e esquemas enviados ao modelo são os mesmos com ou sem o portão, e por isso um pedido feito pelas ferramentas com portão é o mesmo pedido feito sem elas.

Uma proposta é o diff completo da cópia em relação à biblioteca, e não o resumo que o modelo escreveu. pending lista cada arquivo cujos bytes diferem, e diff_text escreve um cabeçalho por arquivo seguido do seu diff unificado. A identidade da proposta é um hash dos bytes alterados, descrito em a seção sobre vinculação. O aprovador recebe o ID da proposta, o resumo, a lista de arquivos alterados, o texto do diff como exibido e o hash. Ele responde com sim ou não, um motivo, e o ID e o hash a que está respondendo. O resumo é mostrado como a afirmação do modelo sobre a mudança, e o portão não o trata como evidência. Se a cópia não tiver nenhuma alteração, finish passa com seu próprio resultado, de modo que uma execução que não mudou nada não recebe nenhuma pergunta. Caso contrário, o aprovador é chamado dentro da chamada da ferramenta, e a execução aguarda a resposta. Quando o portão está em modo de imposição, o corpo da própria ferramenta finish só é executado após um sim.

As diretrizes da OWASP sobre agência excessiva pedem que uma pessoa aprove ações de alto impacto antes de serem realizadas, e que um agente tenha apenas as ferramentas de que precisa. Trata-se de uma orientação, não de uma medição, e este capítulo a trata como a razão do desenho, e não como prova de que o desenho funciona.

O conjunto de tarefas tem 20 tarefas sobre o caso, a maioria pontuada por uma verificação oculta (o conjunto de tarefas cobre todas elas). Suas execuções foram gravadas com o conjunto de ferramentas v1 e sem portão, a partir do Qwen3-4B-Instruct-2507, o modelo que o capítulo 1 reproduz. Um portão deixa cada pedido inalterado, de modo que uma reprodução por ele envia as mesmas requests e recebe as mesmas respostas gravadas. Comece pelo caminho que deve funcionar: a execução gravada de T-04, reproduzida, com uma pessoa que responde sim.

gate-applies-only-on-yes.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""The recorded T-04 run (add the inch) with the gate and a scripted yes: its one changed file reaches the library, andthe hidden check fails before the apply and passes after it. The second part shows two yeses that cannot apply: a copythat changed after the person looked, and an answer that names another proposal."""from lib.case import load_tasksfrom lib.permissions import Answer, Gate, gated, library_copy, replay_task, scriptedfrom lib.tasks import hidden_check_passesfrom lib.tools import V1, Workspacetask = load_tasks(only=["T-04"])[0]with library_copy() as library:    assert not hidden_check_passes(task, library)    gate = Gate(library, scripted((True, "")))    run = replay_task("T-04", gate, library)    print("ended:", run.ended)    print("proposals:", gate.counts["proposals"], "asked:", gate.counts["asked"])    print("applied:", gate.counts["applied"], "files applied:", gate.counts["files applied"])    print("visible tests after the apply:", Workspace(library).run_tests().splitlines()[0])    print("hidden check after the apply:", hidden_check_passes(task, library))    assert run.ended == "finish" and gate.counts["applied"] == 1 and hidden_check_passes(task, library)    run.close()with library_copy() as library, library_copy() as scratch:    ws = Workspace(scratch)    (scratch / "unitcraft" / "extra.py").write_text('"""Extra."""\nTOTAL = 1\n', encoding="utf-8")    def drift(proposal):  # the copy changes in the window between the person's yes and the apply        (scratch / "unitcraft" / "extra.py").write_text('"""Extra."""\nTOTAL = 2\n', encoding="utf-8")        return Answer(True, proposal.id, proposal.sha256)    late = gated(V1, Gate(library, drift)).call(ws, "finish", {"summary": "Add a constant."})    print("drifted copy, handoff:", late.question)    wrong = gated(V1, Gate(library, lambda p: Answer(True, "p-7", p.sha256)))    print("answer for another proposal, handoff:", wrong.call(ws, "finish", {"summary": "Add a constant."}).question)    assert late.end == "ask_user" and "changed after" in late.question    assert not (library / "unitcraft" / "extra.py").exists()
Saídapython gate-applies-only-on-yes.py
ended: finish
proposals: 1 asked: 1
applied: 1 files applied: 1
visible tests after the apply: 8 failed, 22 passed
hidden check after the apply: True
drifted copy, handoff: p-1 was not applied: the copy changed after the answer
answer for another proposal, handoff: p-1 was not applied: the answer is to another proposal or diff

O sim aplica a mudança, e a verificação oculta só passa após a aplicação. A execução termina como finish, e o portão aplica a proposta sobre a qual perguntou. O conjunto visível de testes informa 8 failed, 22 passed depois que a mudança está na biblioteca. Essa contagem não pontua a tarefa. Quem pontua é a verificação oculta, e o exemplo mostra que ela falha antes da aplicação e passa depois dela.

A segunda metade do exemplo verifica dois sins que não podem ser aplicados. No primeiro, a cópia muda dentro do aprovador, depois que a pessoa a examinou. No segundo, a resposta indica outra proposta. Cada um é recusado com motivo próprio: p-1 was not applied: the copy changed after the answer no primeiro caso, e p-1 was not applied: the answer is to another proposal or diff no segundo. Em ambos os casos a biblioteca fica sem alteração, o que o exemplo afirma.

O corpo da ferramenta finish faz parte da mesma regra.

finish-body-waits-for-yes.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""A finish that publishes does its work only after a yes. With a no the body never runs; with a yes it runs once,after the change is applied to the library."""from dataclasses import replacefrom lib.permissions import Gate, answer, gated, library_copyfrom lib.tools import V1, ToolResult, Workspacepublished = []def finish_and_publish(ws, args):    published.append(args.summary)    return ToolResult("run ended", brief="finish", end="finish", summary=args.summary)publishing = replace(V1, tools=tuple(replace(t, run=finish_and_publish) if t.name == "finish" else t                                     for t in V1.tools))def finish_with(yes: bool):    with library_copy() as library, library_copy() as scratch:        gate = Gate(library, lambda p: answer(p, yes, "decided"))        (scratch / "unitcraft" / "n.py").write_text("N = 1\n", encoding="utf-8")        result = gated(publishing, gate).call(Workspace(scratch), "finish", {"summary": "Publish."})        return result, gate, (library / "unitcraft" / "n.py").exists()no_result, _, no_added = finish_with(False)print("no: ended", no_result.end, "| publish ran:", len(published), "| file added:", no_added)yes_result, gate, yes_added = finish_with(True)print("yes: ended", yes_result.end, "| publish ran:", len(published), "| file added:", yes_added)print("applied:", gate.counts["applied"])assert no_result.end == "ask_user" and len(published) == 1 and not no_addedassert yes_result.end == "finish" and yes_added and gate.counts["applied"] == 1
Saídapython finish-body-waits-for-yes.py
no: ended ask_user | publish ran: 0 | file added: False
yes: ended finish | publish ran: 1 | file added: True
applied: 1

O código dá à execução um finish que publica, e reproduz a mesma proposta duas vezes. Com um não, o corpo de publicação não é executado, e o arquivo não é acrescentado: ended ask_user | publish ran: 0 | file added: False. Com um sim, o arquivo é acrescentado e o corpo é executado uma única vez: ended finish | publish ran: 1 | file added: True.

Regra prática: Proponha o diff completo da cópia a partir da única chamada que pode alterar a biblioteca, e calcule o hash desse diff novamente imediatamente antes da aplicação. Uma cópia que se moveu depois que a pessoa a examinou é recusada, qualquer que seja a resposta, porque a aplicação grava os bytes que foram hasheados. Execute o corpo de uma ferramenta somente após um sim.

Uma aprovação responde a uma única solicitação

Um "sim" só tem valor se for para a alteração que a pessoa leu. O problema aparece assim que um mesmo gate recebe mais de uma proposta, como acontece quando várias execuções compartilham um gate. Uma resposta dada a uma alteração poderia ser transferida para a seguinte se nada as relacionasse.

O gate as relaciona por meio de uma identidade. Cada proposta recebe o próximo ID de um contador do seu gate, p-1, depois p-2, e assim por diante, e carrega o hash SHA-256 dos bytes alterados. O hash cobre os bytes exatos de cada arquivo alterado, em ordem de caminho, e não apenas o texto que a pessoa vê. A resposta precisa nomear os dois. O gate compara ambos antes de aplicar qualquer coisa e, em seguida, recalcula o hash da cópia, como descreve a seção sobre o gate. A página da Microsoft sobre aprovação de ferramentas no Agent Framework descreve o mesmo padrão. Ela afirma que uma resposta de aprovação local autoriza uma chamada de ferramenta somente quando corresponde a uma solicitação de aprovação pendente registrada na mesma sessão, e que o framework ignora uma resposta sem vínculo e registra um aviso. Sua nota sobre a desativação diz que desligar a vinculação pode permitir que uma resposta fabricada ou reproduzida aprove uma chamada privilegiada.

O texto que a pessoa lê é escrito por extenso, não em forma bruta. diff_text escreve todo caractere que um terminal poderia executar como um escape visível. Um retorno de carro ou uma sequência de escape, portanto, aparece como texto no diff, e um arquivo que não é texto UTF-8 é mostrado apenas pelo hash de seus bytes.

hidden-diff-lines-shown.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""Two files whose text would hide a line in a terminal: a carriage return that overwrites the line before it, and anescape that erases a line. The proposal shows both written out, so every line the person reads is in the file."""from lib.permissions import Gate, answer, gated, library_copyfrom lib.tools import V1, WorkspaceCR = "HIDDEN_CR = 'not shown'\r# a comment long enough to cover the line before it\n"ESC = "HIDDEN_ESC = 'not shown'\n\x1b[1A\x1b[2K# tidy\n"seen = []def person(proposal):    seen.append(proposal)    return answer(proposal, False, "not this change")with library_copy() as library, library_copy() as scratch:    gate = Gate(library, person)    tools, ws = gated(V1, gate), Workspace(scratch)    tools.call(ws, "write_file", {"path": "unitcraft/a_cr.py", "text": CR})    tools.call(ws, "write_file", {"path": "unitcraft/b_esc.py", "text": ESC})    tools.call(ws, "finish", {"summary": "Add two comment-only modules."})    shown = seen[0].diff    for line in (ln for ln in shown.splitlines() if "HIDDEN" in ln):        print("shown:", line)    print("headers that flag control characters:", shown.count("contains control characters"))    print("raw CR or ESC in the shown text:", sum(ch in shown for ch in "\r\x1b"))    print("applied:", gate.counts["applied"], "refused:", gate.counts["refused"])    assert "\r" not in shown and "\x1b" not in shown and shown.count("contains control characters") == 2    assert gate.counts["applied"] == 0
Saídapython hidden-diff-lines-shown.py
shown: +HIDDEN_CR = 'not shown'\r# a comment long enough to cover the line before it
shown: +HIDDEN_ESC = 'not shown'
headers that flag control characters: 2
raw CR or ESC in the shown text: 0
applied: 0 refused: 1

O script grava dois arquivos cujo conteúdo esconderia uma linha em um terminal. Um tem um retorno de carro que sobrescreveria a linha anterior, e outro tem um escape que apagaria uma linha. A pessoa vê as duas linhas, com os caracteres escritos como escapes. O script imprime 2 cabeçalhos que sinalizam caracteres de controle, e 0 retornos de carro ou escapes brutos no texto exibido. Nesse script, a pessoa responde não, e assim nada é aplicado.

answer-binds-bytes.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""A file that is not UTF-8 text is shown by the hash of its bytes, and the yes binds to those bytes. When the copy'sbytes change after the yes, the apply is refused, even though both versions decode to the same replacement characters."""from lib.permissions import Change, Gate, answer, digest_changes, gated, library_copyfrom lib.tools import V1, Workspacewith library_copy() as library, library_copy() as scratch:    (scratch / "unitcraft" / "blob.bin").write_bytes(b"DATA \xff\n")    def swap_then_yes(proposal):        print("shown as:", proposal.diff.split(";")[0])        (scratch / "unitcraft" / "blob.bin").write_bytes(b"DATA \xfe\n")        return answer(proposal, True)    gate = Gate(library, swap_then_yes)    result = gated(V1, gate).call(Workspace(scratch), "finish", {"summary": "Add a blob."})    print("ended:", result.end)    print("handoff:", result.question)    print("applied:", gate.counts["applied"], "| blob in library:", (library / "unitcraft" / "blob.bin").exists())    one = digest_changes([Change("x.bin", None, b"\xff")])    two = digest_changes([Change("x.bin", None, b"\xfe")])    print("hashes differ for \\xff and \\xfe:", one != two)    assert result.end == "ask_user" and "changed after" in result.question and gate.counts["applied"] == 0    assert one != two
Saídapython answer-binds-bytes.py
shown as: == unitcraft/blob.bin: added, not UTF-8 text
ended: ask_user
handoff: p-1 was not applied: the copy changed after the answer
applied: 0 | blob in library: False
hashes differ for \xff and \xfe: True

O script mostra a outra metade. Ele adiciona um arquivo cujos bytes não são UTF-8 válido, e o aprovador vê == unitcraft/blob.bin: added, not UTF-8 text. Depois do sim, os bytes da cópia são trocados de um byte por outro, e ambos os bytes são decodificados como o mesmo caractere de substituição. A aplicação é recusada: p-1 was not applied: the copy changed after the answer. O script também afirma que as duas sequências de bytes têm hashes diferentes, de modo que o hash não é um hash do texto decodificado.

Duas execuções podem compartilhar um gate em um mesmo exemplo.

approval-in-transcript.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""Two proposals in one transcript, through one gate: the recorded T-04 run is answered yes and its inch reaches thelibrary; a stored T-09 run (fix the Celsius offset) is answered no and handed back. Each answer is logged with theproposal ID and the hash of the diff it answers."""from lib.case import CASEfrom lib.permissions import Gate, library_copy, replay_task, scripted, stored_taskfrom lib.tasks import snapshotwith library_copy() as library:    gate = Gate(library, scripted((True, ""), (False, "not in this change")))    first = replay_task("T-04", gate, library)    second = stored_task("T-09", gate, library)    print("T-04 ended:", first.ended, "| T-09 ended:", second.ended)    print("transcript, T-04:", first.trace.lines()[-1])    print("transcript, T-09:", second.trace.lines()[-1])    for line in gate.log:        print("gate:", line)    print("applied:", gate.counts["applied"], "refused:", gate.counts["refused"])    assert first.ended == "finish" and second.ended == "ask_user" and gate.counts["applied"] == 1    assert snapshot(library, "unitcraft/units.py") != snapshot(CASE, "unitcraft/units.py")    assert snapshot(library, "unitcraft/temperature.py") == snapshot(CASE, "unitcraft/temperature.py")    first.close()    second.close()
Saídapython approval-in-transcript.py
T-04 ended: finish | T-09 ended: ask_user
transcript, T-04: step 5: finish: p-1 yes, applied 1 files
transcript, T-09: step 6: finish: p-2 was not applied: the person said no: not in this change
gate: p-1 1 files, diff 06ee73fd984f: asked
gate: p-1 answer yes, bound to p-1 and 06ee73fd984f
gate: p-1 applied: 1 files
gate: p-2 1 files, diff 95fb833675dd: asked
gate: p-2 answer no, bound to p-2 and 95fb833675dd
gate: p-2 not applied: the person said no: not in this change
applied: 1 refused: 1

O código executa a execução T-04 gravada e responde sim. Em seguida, executa uma execução T-09 armazenada e responde não. A execução T-09 não reproduz as solicitações gravadas. Seus resultados de ferramentas vêm desta cópia, que pode diferir da gravação; por isso, ela injeta as respostas armazenadas passo a passo. Cada resposta é registrada ao lado da sua proposta. A linha da transcrição de T-09 diz step 6: finish: p-2 was not applied: the person said no: not in this change, e a linha de T-04 termina no sim e na aplicação. O log do gate traz os mesmos pares por completo: uma linha para cada resposta, nomeando a proposta e os primeiros doze caracteres do hash que a resposta nomeia. Um leitor que quiser saber qual diff um sim aplicou pode comparar esses caracteres com a proposta que foi exibida. Duas asserções sustentam o resultado: a alteração de T-04 chegou à biblioteca, e a alteração de T-09 não chegou.

Os IDs são contados dentro de um mesmo gate; por isso, dois gates emitem ambos p-1. Esse é um limite em aberto, e a seção de limites em aberto o nomeia.

Regra prática: Dê a cada proposta um ID e o hash de seus bytes, exija que a resposta nomeie os dois e verifique ambos de novo antes de aplicar. Mostre à pessoa o texto com todos os caracteres de controle escritos por extenso. Registre cada resposta como o par, ao lado da sua proposta, para que um leitor possa relacionar um sim à alteração que ele aplicou.

Algumas mudanças são recusadas sem pergunta

Algumas mudanças não cabem a uma pessoa decidir. As regras do caso proíbem o agente de renomear um nome público e de alterar um teste, e um sim não pode suspender uma regra desse tipo. Colocar a pergunta para uma pessoa levaria a decisão ao lugar errado, por isso a verificação recusa essas mudanças antes que qualquer pergunta seja feita.

assess calcula seus motivos a partir do diff em relação à biblioteca, e não a partir do resumo. Ele recusa cinco tipos de mudança. Uma alteração em .github/ é recusada. Um arquivo removido em tests/ é recusado. Uma edição em um arquivo existente em tests/ é recusada. Um arquivo novo em tests/ que não seja um módulo test_*.py é recusado. Um nome removido é recusado: um nome público de nível superior em um módulo unitcraft/ que a biblioteca define e a cópia não define mais, e uma função test_ de nível superior que a biblioteca tem e a cópia não tem. Um novo módulo test_*.py é permitido. As duas árvores são comparadas nome a nome, de modo que uma renomeação aparece como nome removido. As palavras do modelo não podem alterar o resultado, porque os motivos são calculados a partir dos arquivos.

never-class-refused.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""A rename of a public name and the removal of a test, each an edit that succeeds on the copy, with a summary thatsays no approval is needed. The gate reads the diff: both are refused as never-class, and the person is never asked."""from lib.permissions import Gate, gated, library_copy, scriptedfrom lib.tools import V1, WorkspaceREMOVED = ('def test_parses_negative_value():\n    q = parse_quantity("-2 m")\n'           '    assert (q.value, q.unit) == (Decimal("-2"), "m")\n\n\n')with library_copy() as library, library_copy() as scratch:    gate = Gate(library, scripted((True, "")))    tools, ws = gated(V1, gate), Workspace(scratch)    rename = {"path": "unitcraft/parse.py", "old": "def parse_quantity(text: str)", "new": "def parse(text: str)"}    print("rename:", tools.call(ws, "edit_file", rename).text)    print("test removal:", tools.call(ws, "edit_file", {"path": "tests/test_parse.py", "old": REMOVED, "new": ""}).text)    result = tools.call(ws, "finish", {"summary": "Tidy-up: a rename and a removed flaky test. No approval needed."})    print("ended:", result.end)    print("reasons:", result.question)    print("asked:", gate.counts["asked"], "held as never:", gate.counts["held as never"])    assert result.end == "ask_user" and gate.counts["asked"] == 0    assert "removes public name parse_quantity" in result.question    assert "removes test test_parses_negative_value" in result.question
Saídapython never-class-refused.py
rename: edited unitcraft/parse.py
test removal: edited tests/test_parse.py
ended: ask_user
reasons: p-1 was not applied: the harness refuses it: changes the test file tests/test_parse.py; removes public name parse_quantity; removes test test_parses_negative_value
asked: 0 held as never: 1

Duas edições entram na cópia neste exemplo: a renomeação de uma função pública e uma edição em um arquivo de teste que remove um teste. Ambas são concluídas ali, pois edições na cópia são permitidas. A recusa acontece em finish, quando o diff é lido. O resumo que o agente escreve diz que nenhuma aprovação é necessária, e essa afirmação não altera nada.

A execução termina como ask_user, e a entrega registra os motivos por completo: p-1 was not applied: the harness refuses it: changes the test file tests/test_parse.py; removes public name parse_quantity; removes test test_parses_negative_value. Uma asserção afirma que o aprovador nunca foi consultado, o que mostra que a verificação não fez nenhuma pergunta a ninguém.

gutted-test-refused.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""An edit that keeps an existing test's name and removes its assertion is a change to a test file, and the harnessrefuses it without asking. A new test module is not refused for that reason."""from lib.permissions import Change, Gate, assess, gated, library_copy, scriptedfrom lib.tools import V1, Workspacewith library_copy() as library, library_copy() as scratch:    gate = Gate(library, scripted((True, "")))    tools, ws = gated(V1, gate), Workspace(scratch)    edit = {"path": "tests/test_parse.py", "old": '    assert (q.value, q.unit) == (Decimal("-2"), "m")',            "new": "    assert True"}    print("edit:", tools.call(ws, "edit_file", edit).text)    result = tools.call(ws, "finish", {"summary": "Make the negative-value test pass."})    print("ended:", result.end)    print("reasons:", result.question)    print("asked:", gate.counts["asked"], "held as never:", gate.counts["held as never"])    new_module = assess(library, scratch, [Change("tests/test_new.py", None, b"def test_ok():\n    pass\n")])    print("new test module reasons:", new_module)    assert result.end == "ask_user" and gate.counts["asked"] == 0    assert "changes the test file tests/test_parse.py" in result.question and new_module == []
Saídapython gutted-test-refused.py
edit: edited tests/test_parse.py
ended: ask_user
reasons: p-1 was not applied: the harness refuses it: changes the test file tests/test_parse.py
asked: 0 held as never: 1
new test module reasons: []

O script dá um passo menor. O agente edita uma asserção em um teste existente, de modo que o teste passa a afirmar True. A edição é recusada sem pergunta, porque qualquer edição em um arquivo existente em tests/ é recusada: p-1 was not applied: the harness refuses it: changes the test file tests/test_parse.py. A mesma verificação aplicada a um novo módulo de teste não encontra motivo para recusá-lo, e o exemplo afirma isso, de modo que adicionar um teste não é recusado por esse motivo.

A verificação é grosseira, e este capítulo diz isso. Ela compara nomes de nível superior, de modo que uma mudança dentro do corpo de uma função pública depende de um sim. Uma reatribuição como parse_quantity = None ainda define o nome, por isso não é recusada. A seção sobre limites em aberto lista os demais.

Regra prática: Recuse uma mudança que o projeto proíbe, lendo o seu diff em relação a uma lista que o harness controla, e nomeie na entrega a regra que ela violou. Mantenha a lista curta e diga o que ela não verifica, pois uma checagem sobre nomes não protege o que uma função faz. Um sim não pode tornar permitida uma mudança proibida, por isso não peça um.

Recusas voltam ao modelo

Uma negativa é uma resposta que a execução precisa tratar. Se o harness a descartasse, a mudança desapareceria, e o agente não teria como saber por que o trabalho não foi aceito. Por isso, o gate devolve a recusa ao modelo como resultado de ferramenta, na mesma forma que o capítulo 3 usa para um argumento inválido, e encerra a execução como ask_user, um encaminhamento cuja pergunta é o mesmo texto (erros que o modelo consegue ler).

Uma recusa é um resultado de ferramenta, então ocupa espaço no contexto como qualquer outro resultado, e o capítulo 5 a contabiliza ali (a janela que o modelo tem). A página do Microsoft Agent Framework inclui um exemplo em Go que devolve negativas assim como aprovações, para que o modelo possa responder à decisão da pessoa.

refusal-handed-back.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""The recorded T-04 run with the gate and a scripted no. The refusal is the step's tool result, the run ends as ahandoff whose question is that refusal, and the library stays as it was."""from lib.case import CASE, load_tasksfrom lib.loop import run_taskfrom lib.models import ReplayModelfrom lib.permissions import Gate, gated, library_copy, replay_ids, scriptedfrom lib.tasks import snapshotfrom lib.tools import V1task = load_tasks(only=["T-04"])[0]with library_copy() as library:    gate = Gate(library, scripted((False, "the inch belongs in a later change")))    run = run_task(ReplayModel("task-set", "T-04"), task, gated(V1, gate), max_steps=V1.step_cap,                   ids=replay_ids("T-04"), case=library)    print("ended:", run.ended)    print("last step:", run.trace.lines()[-1])    print("handoff question:", run.question)    print("refused:", gate.counts["refused"], "applied:", gate.counts["applied"])    unchanged = snapshot(library, ".") == snapshot(CASE, ".")    print("library unchanged:", unchanged)    assert run.ended == "ask_user" and run.question.startswith("p-1 was not applied") and unchanged    run.close()
Saídapython refusal-handed-back.py
ended: ask_user
last step: step 5: finish: p-1 was not applied: the person said no: the inch belongs in a later change
handoff question: p-1 was not applied: the person said no: the inch belongs in a later change
refused: 1 applied: 0
library unchanged: True

O mesmo replay do T-04 é executado novamente, desta vez com uma negativa e um motivo. A execução termina como ask_user, e o último passo é a própria recusa. A pergunta que o encaminhamento carrega é o texto da recusa, que diz p-1 was not applied: the person said no: the inch belongs in a later change. O motivo da pessoa está nesse texto, então quem lê o encaminhamento vê o que foi decidido e por quê. A biblioteca não é alterada, e o exemplo também verifica isso.

Regra prática: Devolva uma negativa ao modelo como resultado de ferramenta que traga o motivo da pessoa, e encerre a execução como um encaminhamento cuja pergunta seja o mesmo texto. Não engula a negativa, e não a levante como exceção que o loop precise capturar.

O wrapper verifica cada chamada

O gate verifica o que chega à biblioteca por meio de finish. Outra coisa pode alterar a biblioteca: o código que run_tests executa. Por isso, o gate envolve cada ferramenta em um guarda que compara os bytes da biblioteca antes e depois da chamada. Se os bytes mudaram, e o gate não aplicou a alteração por conta própria, a execução termina como library_changed, e o handoff indica os arquivos. Essa é a sétima forma de a execução terminar: o capítulo 2 apresenta seis formas vindas do loop, e o guarda acrescenta esta. Nada é restaurado, e nada mais é executado sobre a biblioteca alterada.

library-guard-fails-closed.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""A test module written into the copy makes run_tests write the library. The guard sees the library's bytes changearound the run_tests call and ends the run as library_changed. It reports the file and restores nothing."""from lib.permissions import Gate, gated, library_copy, scriptedfrom lib.tools import V1, Workspacewith library_copy() as library, library_copy() as scratch:    marker = library / "unitcraft" / "marker.py"    test_module = ("from pathlib import Path\n"                   f"Path({str(marker)!r}).write_text('MARK = 1\\n', encoding='utf-8')\n")    gate = Gate(library, scripted())    tools, ws = gated(V1, gate), Workspace(scratch)    print("write test module:", tools.call(ws, "write_file", {"path": "tests/test_marker.py", "text": test_module}).text)    result = tools.call(ws, "run_tests", {})    print("run_tests ended:", result.end)    print("handoff:", result.question)    print("marker written:", marker.exists(), "| library changes counted:", gate.counts["library changed"])    print("proposals:", gate.counts["proposals"])    assert result.end == "library_changed" and marker.exists() and "unitcraft/marker.py" in result.question    assert gate.counts["proposals"] == 0
Saídapython library-guard-fails-closed.py
write test module: wrote tests/test_marker.py
run_tests ended: library_changed
handoff: the case library changed around run_tests: unitcraft/marker.py; the run stops, and nothing is restored
marker written: True | library changes counted: 1
proposals: 0

O script grava um módulo de teste na cópia. Quando a execução dos testes o importa, o módulo grava um marcador na biblioteca. O guarda encerra a execução com library_changed, e o handoff lê the case library changed around run_tests: unitcraft/marker.py; the run stops, and nothing is restored. O arquivo marcador está na biblioteca, e nenhuma proposta foi feita: 0. O guarda informa a gravação depois, como explica a seção sobre a cópia.

A chamada de uma ferramenta é verificada de uma segunda forma, pelo nome.

A tabela em lib/permissions.py é a única fonte da classe de uma ferramenta, e uma ferramenta que não esteja nela recebe a classe never. O gate recusa essa chamada antes que o código da própria ferramenta seja executado, e a recusa volta ao modelo como texto. A descrição da ferramenta não importa aqui: uma descrição que diz que a ferramenta apenas lê é uma afirmação, e quem decide é a tabela.

unknown-tool-refused.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""A tool outside the harness's table is refused before its own code runs, even when its description says it onlyreads. The refusal goes back to the model as text, and the tool's body never runs."""from dataclasses import replacefrom lib.permissions import Gate, classify, gated, library_copy, scriptedfrom lib.tools import V1, NoArgs, Tool, ToolResult, Workspaceran = []def reset(ws, args):  # stands in for any effect the table does not know about    ran.append(1)    return ToolResult("did something", brief="did something")with library_copy() as library, library_copy() as scratch:    gate = Gate(library, scripted())    extra = Tool("reset_library", "A read-only helper.", NoArgs, reset)    tools = gated(replace(V1, tools=V1.tools + (extra,)), gate)    result = tools.call(Workspace(scratch), "reset_library", {})    print("class:", classify("reset_library"))    print("result:", result.text)    print("body ran:", len(ran))    print("never calls:", gate.counts["never calls"])    assert not ran and result.text.startswith("error:") and gate.counts["never calls"] == 1
Saídapython unknown-tool-refused.py
class: never
result: error: reset_library is not a tool this harness runs
body ran: 0
never calls: 1

O script adiciona uma ferramenta cuja descrição diz que se trata de um auxiliar somente leitura, e a chama. Sua classe é never, e seu resultado é error: reset_library is not a tool this harness runs. O corpo dela foi executado 0 vezes, e o gate contou 1 chamada que nunca ocorreu. O capítulo 9 aplica esta regra às ferramentas MCP, cujas anotações vêm do servidor e não constituem uma classe.

Regra prática: Registre a classe de cada ferramenta na tabela, e recuse qualquer nome que a tabela não liste antes que o seu corpo seja executado.

Listas de permissão não pulam a verificação

A forma usual de pular um portão é uma lista de permissão. Uma ferramenta que está na lista roda sem nenhuma pergunta, e um portão colocado na pergunta fica então contornado para essa ferramenta. No Agent SDK, uma ferramenta aprovada em uma etapa anterior pula o callback de aprovação, de modo que verificações que existem apenas no callback são contornadas para essa ferramenta. A página do Agent SDK diz isso. O Claude Code ordena suas regras de outra maneira: negação primeiro, depois pergunta, depois permissão, e a página de permissões dele diz que uma regra de permissão não pode abrir uma exceção em uma regra de negação.

Este portão não tem lista de permissão. Toda ferramenta do conjunto passa pelo invólucro, que recusa um nome que a tabela não lista, e a verificação sobre uma mudança fica em finish, onde o diff é lido. Nenhuma flag em uma ferramenta decide se essa verificação roda, porque nenhuma ferramenta está isenta do invólucro. Um portão que depende de uma flag que o modelo ou um servidor pode definir não é um portão. O Capítulo 9 aplica essa regra às ferramentas MCP, e elas passam pelas aprovações deste capítulo, e não por uma lista de permissão.

Regra prática: Não deixe que um nome, uma descrição ou uma flag de uma ferramenta ou do seu servidor decida se a verificação roda. Coloque a verificação no caminho que toda mudança feita pelas ferramentas precisa percorrer. Código que os testes rodam está fora desse caminho, como a seção sobre cópias diz, e a flag descreve a ferramenta e nada além disso.

Em todo o conjunto de tarefas

Até aqui, cada exemplo acompanhou uma única execução. A pergunta para o caso é o que o portão faz em todas as execuções registradas, incluindo as execuções que não deveriam alterar nada.

gate-over-task-set.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""The 20 recorded task-set runs replayed with the gate observing, each matching its recorded ending and step count, andthe gate counting what it would have held (the four stop tasks T-16 to T-19 first). Counts only."""from lib.case import CASE, DATA, load_tasksfrom lib.permissions import Gate, library_copy, replay_taskfrom lib.tasks import snapshotfrom lib.trace import IdCounterimport jsonCHANGES = ("edit_file", "write_file")rows = (DATA / "recorded" / "task-set" / "runs.jsonl").read_text(encoding="utf-8").splitlines()recorded = {r["task"]: r for r in map(json.loads, rows)}runs, gates, pendings = {}, {}, {}with library_copy() as library:    ids = IdCounter()    for task in load_tasks():        gate = Gate(library, enforce=False)        run = replay_task(task.id, gate, library, ids=ids)        assert (run.ended, run.steps) == (recorded[task.id]["ended"], recorded[task.id]["steps"]), task.id        runs[task.id], gates[task.id], pendings[task.id] = run, gate, gate.settle(run.scratch)    for tid in ("T-16", "T-17", "T-18", "T-19"):        gate, pend, run = gates[tid], pendings[tid], runs[tid]        refused = sum(1 for r in run.trace.records if r["tool"] in CHANGES and r["brief"].startswith("error"))        print(f"{tid} ended: {run.ended}, steps: {run.steps}")        print(f"  change calls: {gate.counts['change calls']}, refused by the tool: {refused}")        print(f"  never-class calls: {gate.counts['never calls']}, changes in the copy at the end: {len(pend.files)}")        print(f"  held as never: {len(pend.never)}, waiting for a yes: {len(pend.files) - len(pend.never)}")    changed = sorted(t for t in pendings if pendings[t].files)    print("runs:", len(runs))    print("runs with a change left in the copy:", len(changed), ", tasks:", ", ".join(changed))    print("change calls, all runs:", sum(g.counts["change calls"] for g in gates.values()))    print("never-class calls, all runs:", sum(g.counts["never calls"] for g in gates.values()))    print("held as never, all runs:", sum(len(p.never) for p in pendings.values()))    print("proposals that would wait for a yes, all runs:", sum(g.counts["waiting for a yes"] for g in gates.values()))    print("library changed by the replays:", snapshot(library, ".") != snapshot(CASE, "."))    assert snapshot(library, ".") == snapshot(CASE, ".") and gates["T-18"].counts["never calls"] == 1    for run in runs.values():        run.close()
Saídapython gate-over-task-set.py
T-16 ended: step_cap, steps: 16
  change calls: 8, refused by the tool: 8
  never-class calls: 0, changes in the copy at the end: 0
  held as never: 0, waiting for a yes: 0
T-17 ended: ask_user, steps: 9
  change calls: 4, refused by the tool: 4
  never-class calls: 0, changes in the copy at the end: 0
  held as never: 0, waiting for a yes: 0
T-18 ended: ask_user, steps: 4
  change calls: 1, refused by the tool: 1
  never-class calls: 1, changes in the copy at the end: 0
  held as never: 0, waiting for a yes: 0
T-19 ended: ask_user, steps: 9
  change calls: 4, refused by the tool: 4
  never-class calls: 0, changes in the copy at the end: 0
  held as never: 0, waiting for a yes: 0
runs: 20
runs with a change left in the copy: 5 , tasks: T-04, T-05, T-08, T-09, T-14
change calls, all runs: 70
never-class calls, all runs: 1
held as never, all runs: 0
proposals that would wait for a yes, all runs: 5
library changed by the replays: False

Este exemplo reexecuta todas as execuções registradas do conjunto de tarefas através de um portão que apenas observa, sem aplicar bloqueios. O portão decide como decidiria de fato, conta o que reteria e devolve o resultado próprio de cada ferramenta, de modo que cada execução termina onde terminou na gravação. Cada reexecução é verificada para confirmar que coincide com o desfecho e com o número de passos registrados, e a biblioteca é deixada como foi encontrada. Estas são contagens do que o portão faria, e é isso que torna seguro testá-lo antes de ativar a aplicação.

As tarefas de parada T-16 a T-19 tentaram, cada uma, alterar arquivos, e as ferramentas recusaram todas essas chamadas, de modo que nenhuma das cópias foi alterada. O portão contou as chamadas. T-18 é a única tarefa que tentou gravar em .github/. O portão contou essa chamada como uma chamada da classe never, 1 no total. Ele reteve 0 alterações como never, porque a ferramenta já havia recusado a chamada antes que qualquer alteração chegasse à cópia.

Quando uma cópia chegou a manter uma alteração, o portão teria pedido a uma pessoa que se pronunciasse sobre ela. Em todas as reexecuções, 5 propostas aguardariam um sim. As contagens mostram o que o portão faria com essas cópias. Elas não podem mostrar o que uma pessoa responderia, e é por isso que os exemplos deste capítulo usam respostas roteirizadas, e por que um aprovador real precisa ser uma pessoa, ou um processo que uma pessoa controla.

Regra prática: Antes de ativar a aplicação de um portão, reexecute as execuções registradas por ele sem aplicação, e compare cada desfecho e cada contagem com o que você esperava. Uma contagem que o surpreenda é um achado sobre o portão ou sobre as execuções, e você o resolve antes que alguém passe a depender do portão.

Padrões de fornecedores que deixariam uma mudança passar

Várias das falhas abaixo vêm de padrões que parecem razoáveis. Cada um é uma afirmação que o leitor pode acreditar, confrontada com o que a documentação do fornecedor diz e com o que este harness faz. As afirmações do fornecedor são citadas com suas páginas, e nenhuma delas foi executada para este livro.

  • Uma regra de permissão pode sobrescrever uma negação. A documentação do Claude Code diz o contrário: a negação é avaliada primeiro, como a seção sobre a lista de permissões observa.
  • Modo bypass significa que não há portão. A documentação do SDK afirma que as regras de negação e de pergunta continuam valendo no modo bypass, e que a lista allowed_tools não o limita.
  • Aprovar uma vez aprova para sempre. A tabela do Claude Code restringe a escolha "não perguntar de novo" a um repositório e a um comando, no caso de comandos de shell, e à sessão, no caso de modificação de arquivos. A página da Microsoft afirma que as aprovações permanentes persistem no estado da sessão e não estão vinculadas à instância da ferramenta que as criou; por isso, uma ferramenta substituta com o mesmo nome pode corresponder a uma regra salva.
  • Qualquer resposta serve. O Agent Framework da Microsoft ignora, por padrão, uma resposta que não esteja vinculada a uma solicitação pendente. Aqui, a resposta deve nomear a proposta e o seu hash, como a seção de vinculação mostra.
  • Um hook que diz allow pula as verificações. A documentação do SDK afirma que um hook que retorna allow não pula as etapas de deny e de ask.
  • O próprio texto do modelo pode conceder a aprovação. Um resumo que diz "approved" ou "no approval needed" não altera nada neste harness. O exemplo da classe never mostra que a afirmação do resumo não muda a recusa, porque a recusa vem do diff.

Regra prática: Quando o padrão de um fornecedor permite que uma resposta, uma flag ou um hook tome o lugar de uma verificação, não copie esse padrão. Escreva a verificação de modo que ela nomeie o que aprova: a proposta, os seus bytes e a regra que ela aplica. Em seguida, teste que uma resposta errada, uma cópia movida e uma aprovação apenas alegada falhem, cada uma delas.

O que este portão não cobre

A revisão de segurança do código deste capítulo deixou em vigor os limites abaixo, e esta seção é o único lugar que os lista. Cada um é uma lacuna no código didático, e nenhuma delas é resolvida neste capítulo.

  • Código que o agente executa (cópia). run_tests executa código escrito pelo modelo com os próprios direitos do harness. O portão relata uma escrita na biblioteca depois que ela acontece e não restaura nada. O sandbox do capítulo 7 dá aos testes limites e um ambiente limpo, mas não impede escritas em outros caminhos. Um contêiner ou uma máquina virtual é a principal defesa, e nenhum exemplo aqui executa um.
  • Verificações de nomes de nível superior (F-7). A classe never compara nomes de nível superior em unitcraft/ e tests/, e não vai além disso. Um nome definido somente dentro de um bloco não é contado em nenhuma das duas árvores. Uma alteração dentro do corpo de uma função pública, e uma reatribuição como parse_quantity = None, aguardam um sim em vez de serem recusadas.
  • Exceções do aprovador (F-8). Um aprovador que lança uma exceção encerra o laço com essa exceção, e nada é aplicado. Isso não é um repasse. Uma ferramenta que lança um erro diferente de ToolError também escapa do laço: em uma sonda sobre uma cópia de rascunho do código atual, um surrogate isolado em edit_file truncou o arquivo da cópia para zero bytes e depois lançou UnicodeEncodeError.
  • IDs de escopo de execução (F-9). Cada portão numera suas propostas a partir de p-1. Uma resposta registrada para o p-1 de um portão corresponde, portanto, ao p-1 de outro portão sempre que os dois diffs tiverem os mesmos bytes, de modo que uma resposta reaproveitada de um log antigo pode aprovar uma alteração em outra execução. Os bytes são os exibidos, mas o ID não é único entre execuções. Um log mantido entre execuções precisa também do ID da execução.
  • Links simbólicos (F-10). A listagem de arquivos do portão segue um link simbólico na cópia. Um link para um arquivo fora da cópia traz os bytes desse arquivo para o diff, e um sim que cobre o diff pode então aplicá-los à biblioteca como um arquivo regular. A pessoa vê esses bytes no diff, mas a proposta lê um arquivo que a cópia não possui. A correção é ignorar os links, e este capítulo não a faz.
  • O que a pessoa lê. O sim cobre o diff tal como o aprovador o mostrou. Um aprovador que mostra apenas parte do texto dá à pessoa menos do que o hash cobre, e os exemplos deste capítulo mostram o diff completo.

Regra prática: Escreva cada limite ao lado do código de onde ele vem, e nomeie-o uma única vez, em um só lugar, para que o leitor possa ver o que o portão não faz antes de confiar nele.

Decisões tomadas neste capítulo

As decisões abaixo são curtas o bastante para serem conferidas com os exemplos acima.

  • A cópia é onde as ferramentas próprias do harness escrevem, e o harness altera a biblioteca por um único caminho de escrita, chamado depois de um sim. Um contêiner ou uma máquina virtual é a principal defesa para o código que a execução roda. A cópia e o gate são código didático, e os limites em aberto dizem o que eles deixam em aberto.
  • O gate fica em finish e lê o diff inteiro da cópia, não o resumo.
  • As classes vêm da tabela própria do harness. Nem as palavras do modelo nem a descrição de uma ferramenta as definem, e uma ferramenta que a tabela não lista é recusada antes que o seu corpo seja executado.
  • Um sim vincula-se ao ID de uma proposta e ao hash SHA-256 de seus bytes, e o hash da cópia é calculado de novo imediatamente antes da aplicação.
  • O corpo do próprio finish só roda depois de um sim.
  • Uma recusa encerra a execução como ask_user, e o motivo dado pela pessoa torna-se a pergunta.
  • O harness roda sem interface, com um callback. Não se trata do modo dontAsk do fornecedor, e o livro não o chama assim.

Três coisas ficam em aberto de propósito. O aprovador pertence ao chamador, e os exemplos o simulam por script para que rodem offline. A lista de alterações que o harness recusa de imediato é curta, e uma lista maior é uma decisão dos mantenedores do caso, não do gate. O gate verifica alterações na biblioteca, não os comandos que o agente executa, tema que o capítulo 7 aborda.

O harness aplica uma alteração na biblioteca somente depois de um sim, e um sim aplica apenas os bytes que a pessoa viu e que foram calculados em hash. O gate não verifica o código que a execução roda. O guarda detecta uma alteração que esse código faça na biblioteca e encerra a execução, mas não a impede; as defesas para isso estão na seção sobre a cópia.

Regra prática: Registre cada decisão de um gate junto do exemplo que a mostra, e liste o que o gate deixa para o seu chamador. Uma decisão sem exemplo por trás é uma afirmação, e o capítulo a rotula como tal.

Este capítulo, nesta edição

Edição 2026.11.2Exemplos aprovados em 20 de nov de 202612 de 12 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.2.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 6 de 12: Coloque portões nas ferramentas que alteram as coisas

  1. A cópia vem primeiro
  2. Em qual modo este harness está
  3. O portão fica em finish
  4. Uma aprovação responde a uma única solicitação
  5. Algumas mudanças são recusadas sem pergunta
  6. Recusas voltam ao modelo
  7. O wrapper verifica cada chamada
  8. Listas de permissão não pulam a verificação
  9. Em todo o conjunto de tarefas
  10. Padrões de fornecedores que deixariam uma mudança passar
  11. O que este portão não cobre
  12. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos