Controla las herramientas que cambian cosas
Unos 32 minutos de lectura, con 12 ejemplos en 12 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.2. Lee el original
En esta página
- La copia va primero
- Qué modo tiene este arnés
- La puerta está en finish
- Una aprobación responde a una sola solicitud
- Algunos cambios se rechazan sin preguntar
- Las negativas vuelven al modelo
- El envoltorio verifica cada llamada
- Las listas de permitidos no omiten la comprobación
- A lo largo del conjunto de tareas
- Valores por defecto de los proveedores que dejarían pasar un cambio
- Lo que esta compuerta no cubre
- Decisiones que tomó este capítulo
Al final de este capítulo podrás mantener los cambios de un agente en su propia copia hasta que una persona diga que sí, comprobar que ese sí cubre exactamente el cambio que leyeron, y devolver un no al agente como la razón por la que su ejecución se detuvo.
El agente de este libro mantiene unitcraft, una biblioteca cuyo responsable es dueño de cada cambio que entra en ella, y trabaja sobre una copia temporal de esa biblioteca. Sus pruebas y sus ediciones ocurren en la copia. Aun así, hace falta decidir cuándo un cambio llega a la biblioteca que es del responsable, y en este caso el responsable es la persona que abrió la incidencia. La tarea T-04 muestra claramente lo que está en juego. Su incidencia pide una unidad más, la pulgada, y la copia del agente contiene una edición que la añade. Si esa edición entra o no es una decisión de una persona, y el agente no debe tomarla por ella.
Este capítulo construye la parte del arnés que pregunta. Las herramientas de archivos del agente escriben solo en la copia de la ejecución, y la biblioteca cambia únicamente cuando el arnés aplica el diff de una ejecución tras el sí de una persona. Sobre eso se añaden dos comprobaciones: una puerta que lee el diff en finish, y un guardia que compara los bytes de la biblioteca alrededor de cada llamada a una herramienta. La puerta y el guardia son código didáctico y una segunda capa, y ninguno de los dos es un entorno aislado. La defensa principal para el código que escribe el agente es un contenedor o una máquina virtual, que explica el capítulo 7. Ningún ejemplo de aquí ejecuta uno, y ninguna grabación muestra uno. Cada llamada a una herramienta se envuelve en una comparación de los bytes de la biblioteca del caso, y el guardia falla en modo seguro: cuando la biblioteca ha cambiado, la ejecución termina como library_changed, el arnés no aplica nada y no restaura nada. La primera sección explica qué no detiene la copia.
La copia va primero
Las herramientas de archivos del agente solo llegan a los archivos a través de su copia. Cada ejecución tiene su propia copia, creada por scratch_copy en run_task, y las herramientas trabajan a través de un Workspace con raíz en esa copia. Workspace.locate resuelve toda ruta que da el modelo. Rechaza una ruta que es absoluta, una con una parte .., una con un byte NUL o una barra invertida, una que se resuelve mediante un enlace simbólico hacia un lugar fuera de la copia, y cualquier escritura dentro de .github/. A través de estas herramientas, una ruta que no se resuelve dentro de la copia nunca llega al disco.
Estas comprobaciones cubren las rutas que usan las herramientas. No cubren el código que ejecuta el agente. run_tests ejecuta pytest sobre la copia, y pytest ejecuta lo que el modelo haya escrito allí. Un módulo de pruebas que añade el modelo también es código. La ejecución de pruebas lo importa y lo ejecuta con los derechos de usuario del arnés y sin sandbox, así que puede escribir en cualquier ruta que ese usuario pueda escribir, incluida la biblioteca. El ejecutor no carga archivos conftest.py (run_pytest pasa --noconftest), pero sí recoge módulos de pruebas, y esa es la vía a la que se refiere esta sección. La puerta no puede impedir esa escritura, porque solo lee el diff en finish. La guarda de la biblioteca, en su sección, ve la escritura una vez que run_tests regresa, termina la ejecución como library_changed y no restaura nada. Detecta la escritura después de que ocurre. No la impide.
Este es el lado abierto del arnés, y es la principal limitación de este capítulo. El capítulo 7 describe el sandbox didáctico del libro, que ejecuta los comandos del agente con límites y un entorno limpio. Su tabla enumera lo que deja abierto, y las escrituras fuera de la copia están en esa lista. Un contenedor o una máquina virtual es la defensa principal para ejecutar código escrito por un modelo, y el capítulo 7 explica ambos. Las comprobaciones de este capítulo son código didáctico, escrito para que puedas abrirlo, copiarlo y probarlo. No sustituyen ese aislamiento.
La biblioteca cambia en un solo punto. apply en lib/permissions.py escribe bytes nuevos en la biblioteca, y su único llamador es la respuesta de la puerta a una propuesta, tras un sí. library_copy crea la biblioteca desechable a la que se aplican los ejemplos, de modo que la carpeta de casos del libro nunca se escribe. Cuando una ejecución termina, Gate.settle informa de lo que la copia aún contiene, y nada de la copia se vuelve a escribir en la biblioteca.
Una escritura también puede fallar a mitad de una aplicación. El siguiente ejemplo da una propuesta de dos archivos y pone una carpeta donde va el segundo archivo, de modo que la segunda escritura falla.
1"""A proposal of two files where the second cannot be written, because a folder stands where it goes. The first file2is put back, the error goes back as the handoff, and the library holds the bytes it held before the finish."""3from lib.case import CASE4from lib.permissions import Gate, answer, gated, library_copy5from lib.tasks import snapshot6from lib.tools import V1, Workspace78with library_copy() as library, library_copy() as scratch:9 (library / "unitcraft" / "extra.py").mkdir()10 before = snapshot(library, ".")11 (scratch / "README.md").write_text("A new line in the readme.\n", encoding="utf-8")12 (scratch / "unitcraft" / "extra.py").write_text('"""Extra."""\nTOTAL = 1\n', encoding="utf-8")13 gate = Gate(library, lambda p: answer(p, True))14 result = gated(V1, gate).call(Workspace(scratch), "finish", {"summary": "Two files."})15 print("ended:", result.end)16 print("handoff:", result.question)17 print("README as before:", snapshot(library, "README.md") == snapshot(CASE, "README.md"))18 print("library bytes unchanged:", snapshot(library, ".") == before)19 print("applied:", gate.counts["applied"], "refused:", gate.counts["refused"])20 assert result.end == "ask_user" and "apply failed (IsADirectoryError)" in result.question21 assert snapshot(library, ".") == before and gate.counts["applied"] == 0
python apply-all-or-nothing.pyended: 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 archivo que había tocado y cada carpeta que había creado, y la puerta mantiene la propuesta con el error como motivo: p-1 was not applied: apply failed (IsADirectoryError); library restored. El README, que se escribió primero, queda como estaba antes del cierre, y los bytes de la biblioteca no cambian. La puerta captura un OSError y lo trata como propuesta retenida. Cualquier otra excepción también restaura los archivos y después se vuelve a lanzar, y ningún ejemplo aquí muestra esa vía.
Regla práctica: Da a cada ejecución su propia copia, rechaza toda ruta que se resuelva fuera de ella, y deja que exactamente una función escriba en el original, llamada solo después de un sí. Luego nombra lo que el código de la ejecución aún puede hacer al original, comprueba eso con una guarda, y no cuentes la puerta como protección.
Qué modo tiene este arnés
Una puerta de control necesita primero la respuesta a una pregunta: ¿quién responde cuando el agente se detiene a preguntar? El modo interactivo de Claude Code pregunta a una persona de la sesión. El Claude Agent SDK ofrece varios modos de permisos que difieren en este punto, y un arnés debe indicar a cuál se parece, porque la respuesta determina qué ocurre con una llamada que necesita aprobación cuando nadie puede responder. Este arnés no tiene terminal ni sesión. Es una ejecución sin interfaz, y la única parte que puede responder es un callback que pasa quien lo llama.
La documentación del fabricante separa los casos. La página de permisos de Claude Code indica que las reglas se evalúan en el orden denegar, preguntar, permitir, y que la primera coincidencia decide el resultado. También indica que Claude Code pide confirmación antes de modificar archivos por defecto, y que el trabajo de solo lectura dentro del directorio de trabajo se ejecuta sin preguntar. La página de permisos del Agent SDK describe un modo dontAsk, en el que cualquier llamada que de otro modo pediría confirmación se deniega sin llamar al callback de aprobación. Ninguno de los dos productos se ejecutó para este capítulo, así que las afirmaciones sobre ellos son del fabricante y están marcadas como tales.
Este arnés conserva su callback. Un cambio que necesita un sí llama al aprobador y espera la respuesta. El modo dontAsk del fabricante difiere en un aspecto que aquí importa: deniega esa llamada sin invocar el callback, y este arnés siempre lo invoca. El libro llama a esto una ejecución sin interfaz con callback, y no dontAsk. La puerta es la misma sea cual sea el adaptador de modelo que use la ejecución, porque envuelve las herramientas y no el modelo. El protocolo de modelo del capítulo 4 es la parte que cambia de un modelo a otro.
Regla práctica: Nombra el modo antes de añadir una puerta. Cuando quien llama dispone de un callback que puede responder, haz que la puerta lo llame y espere la respuesta. Una puerta construida sin aprobador se niega a arrancar: el código de este capítulo lanza un error. Un diseño que delega cuando nada puede responder necesita su propio camino, y ningún ejemplo de este capítulo muestra uno.
La puerta está en finish
La mayor parte de lo que hace el agente no cambia nada de lo que el mantenedor posee. Lista archivos, los lee y ejecuta las pruebas visibles. Sus ediciones sobre la copia son trabajo propio y están pensadas para hacerse. La única llamada que pide un cambio en la biblioteca es finish, así que la verificación de la puerta se sitúa ahí, y finish es el lugar donde se hace una propuesta.
La puerta envuelve cada herramienta del conjunto, y la clase de cada herramienta sale de una única tabla en lib/permissions.py. Las lecturas (list_files, read_file, run_tests y ask_user) pasan sin cambios, y el guardia de la biblioteca vigila cada una de ellas. run_tests está en la clase de lectura, pero ejecuta código que escribió el modelo, como dice la sección sobre la copia. Las ediciones y escrituras (edit_file y write_file) se ejecutan en la copia, y la puerta cuenta cada llamada. finish es una propuesta. Su clase sale de la tabla del arnés y de nada que haya escrito el modelo, así que ni el resumen del modelo ni la descripción de una herramienta la determinan. Los nombres, descripciones y esquemas que se envían al modelo son los mismos con o sin la puerta, de modo que una solicitud hecha a través de las herramientas controladas es la misma solicitud que una hecha sin ellas.
Una propuesta es el diff completo de la copia frente a la biblioteca, no el resumen que escribió el modelo. pending enumera cada archivo cuyos bytes difieren, y diff_text escribe un encabezado por archivo seguido de su diff unificado. La identidad de la propuesta es un hash de los bytes modificados, descrito en la sección sobre la vinculación. El aprobador recibe el ID de la propuesta, el resumen, la lista de archivos modificados, el texto del diff tal como se muestra y el hash. Responde con un sí o un no, un motivo, y el ID y el hash a los que responde. El resumen se muestra como la afirmación del modelo sobre el cambio, y la puerta no lo trata como evidencia. Si la copia no contiene ningún cambio, finish pasa con su propio resultado, de modo que una ejecución que no cambió nada no recibe ninguna pregunta. En caso contrario, el aprobador se llama dentro de la llamada a la herramienta, y la ejecución espera la respuesta. Cuando la puerta está aplicando la regla, el cuerpo de la propia herramienta de finalización solo se ejecuta tras un sí.
La guía de OWASP sobre la agencia excesiva pide que una persona apruebe las acciones de alto impacto antes de tomarlas, y que un agente tenga solo las herramientas que necesita. Eso es una guía, no una medición, y este capítulo la trata como la razón del diseño y no como prueba de que el diseño funcione.
El conjunto de tareas son 20 tareas sobre el caso, la mayoría evaluadas por una comprobación oculta (el conjunto de tareas las cubre todas). Sus ejecuciones se registraron con el conjunto de herramientas v1 y sin puerta, con Qwen3-4B-Instruct-2507, el modelo que el capítulo 1 reproduce. Una puerta deja cada solicitud sin cambios, así que una reproducción a través de ella envía las mismas solicitudes y obtiene las mismas respuestas registradas. Empieza por el camino que debería funcionar: la ejecución registrada de T-04, reproducida, con una persona que responde sí.
1"""The recorded T-04 run (add the inch) with the gate and a scripted yes: its one changed file reaches the library, and2the hidden check fails before the apply and passes after it. The second part shows two yeses that cannot apply: a copy3that changed after the person looked, and an answer that names another proposal."""4from lib.case import load_tasks5from lib.permissions import Answer, Gate, gated, library_copy, replay_task, scripted6from lib.tasks import hidden_check_passes7from lib.tools import V1, Workspace89task = load_tasks(only=["T-04"])[0]10with library_copy() as library:11 assert not hidden_check_passes(task, library)12 gate = Gate(library, scripted((True, "")))13 run = replay_task("T-04", gate, library)14 print("ended:", run.ended)15 print("proposals:", gate.counts["proposals"], "asked:", gate.counts["asked"])16 print("applied:", gate.counts["applied"], "files applied:", gate.counts["files applied"])17 print("visible tests after the apply:", Workspace(library).run_tests().splitlines()[0])18 print("hidden check after the apply:", hidden_check_passes(task, library))19 assert run.ended == "finish" and gate.counts["applied"] == 1 and hidden_check_passes(task, library)20 run.close()2122with library_copy() as library, library_copy() as scratch:23 ws = Workspace(scratch)24 (scratch / "unitcraft" / "extra.py").write_text('"""Extra."""\nTOTAL = 1\n', encoding="utf-8")2526 def drift(proposal): # the copy changes in the window between the person's yes and the apply27 (scratch / "unitcraft" / "extra.py").write_text('"""Extra."""\nTOTAL = 2\n', encoding="utf-8")28 return Answer(True, proposal.id, proposal.sha256)2930 late = gated(V1, Gate(library, drift)).call(ws, "finish", {"summary": "Add a constant."})31 print("drifted copy, handoff:", late.question)32 wrong = gated(V1, Gate(library, lambda p: Answer(True, "p-7", p.sha256)))33 print("answer for another proposal, handoff:", wrong.call(ws, "finish", {"summary": "Add a constant."}).question)34 assert late.end == "ask_user" and "changed after" in late.question35 assert not (library / "unitcraft" / "extra.py").exists()
python gate-applies-only-on-yes.pyended: 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
El sí aplica el cambio, y la comprobación oculta solo pasa después de la aplicación. La ejecución termina como finish, y la puerta aplica la propuesta por la que preguntó. El conjunto visible informa 8 failed, 22 passed una vez incorporado el cambio. Ese recuento no puntúa la tarea. La comprobación oculta sí lo hace, y el ejemplo sostiene que falla antes de la aplicación y pasa después de ella.
La segunda mitad del ejemplo comprueba dos síes que no pueden aplicarse. En el primero, la copia cambia dentro del aprobador, después de que la persona la haya revisado. En el segundo, la respuesta nombra otra propuesta. Cada uno se rechaza con su propio motivo: p-1 was not applied: the copy changed after the answer para el primero, y p-1 was not applied: the answer is to another proposal or diff para el segundo. En ambos casos la biblioteca queda sin cambios, lo que el ejemplo afirma.
El cuerpo de la herramienta de finalización forma parte de la misma regla.
1"""A finish that publishes does its work only after a yes. With a no the body never runs; with a yes it runs once,2after the change is applied to the library."""3from dataclasses import replace45from lib.permissions import Gate, answer, gated, library_copy6from lib.tools import V1, ToolResult, Workspace78published = []91011def finish_and_publish(ws, args):12 published.append(args.summary)13 return ToolResult("run ended", brief="finish", end="finish", summary=args.summary)141516publishing = replace(V1, tools=tuple(replace(t, run=finish_and_publish) if t.name == "finish" else t17 for t in V1.tools))181920def finish_with(yes: bool):21 with library_copy() as library, library_copy() as scratch:22 gate = Gate(library, lambda p: answer(p, yes, "decided"))23 (scratch / "unitcraft" / "n.py").write_text("N = 1\n", encoding="utf-8")24 result = gated(publishing, gate).call(Workspace(scratch), "finish", {"summary": "Publish."})25 return result, gate, (library / "unitcraft" / "n.py").exists()262728no_result, _, no_added = finish_with(False)29print("no: ended", no_result.end, "| publish ran:", len(published), "| file added:", no_added)30yes_result, gate, yes_added = finish_with(True)31print("yes: ended", yes_result.end, "| publish ran:", len(published), "| file added:", yes_added)32print("applied:", gate.counts["applied"])33assert no_result.end == "ask_user" and len(published) == 1 and not no_added34assert yes_result.end == "finish" and yes_added and gate.counts["applied"] == 1
python finish-body-waits-for-yes.pyno: ended ask_user | publish ran: 0 | file added: False
yes: ended finish | publish ran: 1 | file added: True
applied: 1
El código le da a la ejecución un finish que publica, y reproduce la misma propuesta dos veces. Ante un no, el cuerpo de publicación no se ejecuta y el archivo no se añade: ended ask_user | publish ran: 0 | file added: False. Ante un sí, el archivo se añade y el cuerpo se ejecuta una vez: ended finish | publish ran: 1 | file added: True.
Regla práctica: Propón el diff completo de la copia desde la única llamada que puede cambiar la biblioteca, y vuelve a calcular el hash de ese diff justo antes de la aplicación. Una copia que se haya movido después de que la persona la revisara se rechaza, diga lo que diga la respuesta, porque la aplicación escribe los bytes que se hashearon. Ejecuta el cuerpo de una herramienta solo después de un sí.
Una aprobación responde a una sola solicitud
Un sí vale algo solo si se refiere al cambio que la persona leyó. El problema aparece en cuanto una misma compuerta ve más de una propuesta, como ocurre cuando varias ejecuciones comparten una compuerta. Una respuesta dada para un cambio podría trasladarse al siguiente si nada vincula ambos.
La compuerta los vincula mediante un identificador. Cada propuesta toma el siguiente ID de un contador de su compuerta, p-1, luego p-2, y así sucesivamente, y lleva el hash SHA-256 de los bytes modificados. El hash cubre los bytes exactos de cada archivo modificado, en orden de ruta, y no solo el texto que la persona ve. La respuesta debe nombrar ambos. La compuerta los compara antes de aplicar nada, y luego vuelve a calcular el hash de la copia, como describe la sección de la compuerta. La página de Microsoft sobre aprobación de herramientas en Agent Framework describe el mismo patrón. Dice que una respuesta de aprobación local autoriza una llamada a una herramienta solo si coincide con una solicitud de aprobación pendiente registrada en la misma sesión, y que el framework ignora una respuesta sin vincular y registra una advertencia. Su nota sobre la desactivación indica que apagar la vinculación puede permitir que una respuesta fabricada o reproducida apruebe una llamada privilegiada.
El texto que lee la persona se escribe explícitamente, no en bruto. diff_text escribe como un escape visible cada carácter sobre el que una terminal podría actuar. Un retorno de carro o una secuencia de escape aparece, por tanto, como texto en el diff, y un archivo que no es texto UTF-8 se muestra solo mediante el hash de sus bytes.
El script escribe dos archivos cuyo contenido ocultaría una línea en una terminal. Uno tiene un retorno de carro que sobrescribiría la línea anterior, y otro tiene un escape que borraría una línea. La persona ve ambas líneas, escapadas. El script imprime 2 que marcan caracteres de control, y 0 en el texto mostrado. Su persona responde no, así que no se aplica nada.
1"""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's2bytes change after the yes, the apply is refused, even though both versions decode to the same replacement characters."""3from lib.permissions import Change, Gate, answer, digest_changes, gated, library_copy4from lib.tools import V1, Workspace56with library_copy() as library, library_copy() as scratch:7 (scratch / "unitcraft" / "blob.bin").write_bytes(b"DATA \xff\n")89 def swap_then_yes(proposal):10 print("shown as:", proposal.diff.split(";")[0])11 (scratch / "unitcraft" / "blob.bin").write_bytes(b"DATA \xfe\n")12 return answer(proposal, True)1314 gate = Gate(library, swap_then_yes)15 result = gated(V1, gate).call(Workspace(scratch), "finish", {"summary": "Add a blob."})16 print("ended:", result.end)17 print("handoff:", result.question)18 print("applied:", gate.counts["applied"], "| blob in library:", (library / "unitcraft" / "blob.bin").exists())19 one = digest_changes([Change("x.bin", None, b"\xff")])20 two = digest_changes([Change("x.bin", None, b"\xfe")])21 print("hashes differ for \\xff and \\xfe:", one != two)22 assert result.end == "ask_user" and "changed after" in result.question and gate.counts["applied"] == 023 assert one != two
python answer-binds-bytes.pyshown 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
El script muestra la otra mitad. Añade un archivo cuyos bytes no son UTF-8 válido, y al aprobador se le muestra == unitcraft/blob.bin: added, not UTF-8 text. Tras el sí, los bytes de la copia se cambian de un byte a otro, y ambos bytes se decodifican como el mismo carácter de reemplazo. La aplicación se rechaza: p-1 was not applied: the copy changed after the answer. El script también afirma que las dos cadenas de bytes tienen hashes distintos, de modo que el hash no es un hash del texto decodificado.
Dos ejecuciones pueden compartir una compuerta en un solo ejemplo.
1"""Two proposals in one transcript, through one gate: the recorded T-04 run is answered yes and its inch reaches the2library; a stored T-09 run (fix the Celsius offset) is answered no and handed back. Each answer is logged with the3proposal ID and the hash of the diff it answers."""4from lib.case import CASE5from lib.permissions import Gate, library_copy, replay_task, scripted, stored_task6from lib.tasks import snapshot78with library_copy() as library:9 gate = Gate(library, scripted((True, ""), (False, "not in this change")))10 first = replay_task("T-04", gate, library)11 second = stored_task("T-09", gate, library)12 print("T-04 ended:", first.ended, "| T-09 ended:", second.ended)13 print("transcript, T-04:", first.trace.lines()[-1])14 print("transcript, T-09:", second.trace.lines()[-1])15 for line in gate.log:16 print("gate:", line)17 print("applied:", gate.counts["applied"], "refused:", gate.counts["refused"])18 assert first.ended == "finish" and second.ended == "ask_user" and gate.counts["applied"] == 119 assert snapshot(library, "unitcraft/units.py") != snapshot(CASE, "unitcraft/units.py")20 assert snapshot(library, "unitcraft/temperature.py") == snapshot(CASE, "unitcraft/temperature.py")21 first.close()22 second.close()
python approval-in-transcript.pyT-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
El código ejecuta la ejecución T-04 registrada y responde sí. Luego ejecuta una ejecución T-09 almacenada y responde no. La ejecución T-09 no reproduce sus solicitudes registradas. Sus resultados de herramientas provienen de esta copia, que puede diferir de la grabación, así que introduce paso a paso las respuestas almacenadas. Cada respuesta se registra junto a su propuesta. La línea de la transcripción para T-09 dice step 6: finish: p-2 was not applied: the person said no: not in this change, y la línea de T-04 termina en el sí y la aplicación. El registro de la compuerta contiene los mismos pares en forma completa: una línea por cada respuesta, que nombra la propuesta y los doce primeros caracteres del hash que la respuesta nombra. Un lector que quiera saber qué diff aplicó un sí puede comparar esos caracteres con la propuesta que se mostró. Dos aserciones sostienen el resultado: el cambio de T-04 llegó a la biblioteca, y el de T-09 no.
Los IDs se cuentan de forma ascendente dentro de una misma compuerta, así que dos compuertas emiten ambas p-1. Es un límite abierto, y la sección de límites abiertos lo señala.
Regla práctica: Asigna a cada propuesta un ID y el hash de sus bytes, exige que la respuesta nombre ambos y vuelve a comprobarlos antes de aplicar. Muestra a la persona el texto con todos los caracteres de control escritos explícitamente. Registra cada respuesta como el par, junto a su propuesta, para que un lector pueda relacionar un sí con el cambio que aplicó.
Algunos cambios se rechazan sin preguntar
Hay cambios que no le corresponde decidir a una persona. Las reglas del caso prohíben al agente renombrar un nombre público y modificar una prueba, y un sí no puede levantar una regla de ese tipo. Preguntarle a una persona trasladaría la decisión al lugar equivocado, así que la compuerta rechaza estos cambios antes de que se haga ninguna pregunta.
assess calcula sus motivos a partir de la diferencia frente a la biblioteca, no a partir del resumen. Rechaza cinco tipos de cambio. Un cambio bajo .github/ se rechaza. Un archivo eliminado bajo tests/ se rechaza. Una edición a un archivo existente bajo tests/ se rechaza. Un archivo nuevo bajo tests/ que no sea un módulo test_*.py se rechaza. Un nombre eliminado se rechaza: un nombre público de nivel superior en un módulo de unitcraft/ que la biblioteca define y la copia ya no define, y una función test_ de nivel superior que la biblioteca tiene y la copia no. Un nuevo módulo test_*.py está permitido. Los dos árboles se comparan nombre por nombre, de modo que un renombramiento aparece como un nombre eliminado. Las palabras del modelo no pueden cambiar el resultado, porque los motivos se calculan a partir de los archivos.
1"""A rename of a public name and the removal of a test, each an edit that succeeds on the copy, with a summary that2says no approval is needed. The gate reads the diff: both are refused as never-class, and the person is never asked."""3from lib.permissions import Gate, gated, library_copy, scripted4from lib.tools import V1, Workspace56REMOVED = ('def test_parses_negative_value():\n q = parse_quantity("-2 m")\n'7 ' assert (q.value, q.unit) == (Decimal("-2"), "m")\n\n\n')89with library_copy() as library, library_copy() as scratch:10 gate = Gate(library, scripted((True, "")))11 tools, ws = gated(V1, gate), Workspace(scratch)12 rename = {"path": "unitcraft/parse.py", "old": "def parse_quantity(text: str)", "new": "def parse(text: str)"}13 print("rename:", tools.call(ws, "edit_file", rename).text)14 print("test removal:", tools.call(ws, "edit_file", {"path": "tests/test_parse.py", "old": REMOVED, "new": ""}).text)15 result = tools.call(ws, "finish", {"summary": "Tidy-up: a rename and a removed flaky test. No approval needed."})16 print("ended:", result.end)17 print("reasons:", result.question)18 print("asked:", gate.counts["asked"], "held as never:", gate.counts["held as never"])19 assert result.end == "ask_user" and gate.counts["asked"] == 020 assert "removes public name parse_quantity" in result.question21 assert "removes test test_parses_negative_value" in result.question
python never-class-refused.pyrename: 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
En este ejemplo entran en la copia dos ediciones: el renombramiento de una función pública y una edición a un archivo de prueba que elimina una prueba. Ambas se completan allí, ya que las ediciones a la copia están permitidas. El rechazo llega en finish, cuando se lee la diferencia. El resumen que escribe el agente dice que no hace falta aprobación, y esa afirmación no cambia nada.
La ejecución termina como ask_user, y el traspaso da los motivos completos: 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. Una aserción comprueba que nunca se le preguntó al aprobador, de modo que la compuerta no le hizo ninguna pregunta a nadie.
1"""An edit that keeps an existing test's name and removes its assertion is a change to a test file, and the harness2refuses it without asking. A new test module is not refused for that reason."""3from lib.permissions import Change, Gate, assess, gated, library_copy, scripted4from lib.tools import V1, Workspace56with library_copy() as library, library_copy() as scratch:7 gate = Gate(library, scripted((True, "")))8 tools, ws = gated(V1, gate), Workspace(scratch)9 edit = {"path": "tests/test_parse.py", "old": ' assert (q.value, q.unit) == (Decimal("-2"), "m")',10 "new": " assert True"}11 print("edit:", tools.call(ws, "edit_file", edit).text)12 result = tools.call(ws, "finish", {"summary": "Make the negative-value test pass."})13 print("ended:", result.end)14 print("reasons:", result.question)15 print("asked:", gate.counts["asked"], "held as never:", gate.counts["held as never"])16 new_module = assess(library, scratch, [Change("tests/test_new.py", None, b"def test_ok():\n pass\n")])17 print("new test module reasons:", new_module)18 assert result.end == "ask_user" and gate.counts["asked"] == 019 assert "changes the test file tests/test_parse.py" in result.question and new_module == []
python gutted-test-refused.pyedit: 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: []
El script da un paso más pequeño. El agente edita una aserción en una prueba existente, de modo que la prueba afirma True. La edición se rechaza sin preguntar, porque cualquier edición a un archivo existente bajo tests/ se rechaza: p-1 was not applied: the harness refuses it: changes the test file tests/test_parse.py. La misma comprobación sobre un nuevo módulo de prueba no encuentra motivo para rechazarlo, y el ejemplo lo afirma, de modo que añadir una prueba no se rechaza por esa razón.
La comprobación es burda, y este capítulo lo dice. Compara nombres de nivel superior, así que un cambio dentro del cuerpo de una función pública espera un sí. Una nueva asignación como parse_quantity = None sigue definiendo el nombre, así que no se rechaza. La sección de límites abiertos enumera el resto.
Regla práctica: Rechaza un cambio que el proyecto prohíbe leyendo su diferencia frente a una lista que es propiedad del arnés, y nombra en el traspaso la regla que infringió. Mantén la lista corta y di qué no comprueba, porque una comprobación sobre nombres no protege lo que hace una función. Un sí no puede permitir un cambio prohibido, así que no pidas uno.
Las negativas vuelven al modelo
Un no es una respuesta a la que el arnés debe dar curso. Si el arnés lo descartara, el cambio desaparecería y el agente no tendría forma de saber por qué su trabajo no se aceptó. Por eso la compuerta devuelve la negativa al modelo como resultado de la herramienta, en la misma forma que el capítulo 3 usa para un argumento incorrecto, y termina la ejecución como ask_user, un traspaso cuya pregunta es el mismo texto (errores que el modelo puede leer).
Una negativa es un resultado de herramienta, así que ocupa espacio en el contexto como cualquier otro resultado, y el capítulo 5 lo cuenta ahí (la ventana que tiene el modelo). La página de Agent Framework de Microsoft incluye un ejemplo en Go que devuelve tanto las denegaciones como las aprobaciones, de modo que el modelo pueda responder a la decisión de la persona.
1"""The recorded T-04 run with the gate and a scripted no. The refusal is the step's tool result, the run ends as a2handoff whose question is that refusal, and the library stays as it was."""3from lib.case import CASE, load_tasks4from lib.loop import run_task5from lib.models import ReplayModel6from lib.permissions import Gate, gated, library_copy, replay_ids, scripted7from lib.tasks import snapshot8from lib.tools import V1910task = load_tasks(only=["T-04"])[0]11with library_copy() as library:12 gate = Gate(library, scripted((False, "the inch belongs in a later change")))13 run = run_task(ReplayModel("task-set", "T-04"), task, gated(V1, gate), max_steps=V1.step_cap,14 ids=replay_ids("T-04"), case=library)15 print("ended:", run.ended)16 print("last step:", run.trace.lines()[-1])17 print("handoff question:", run.question)18 print("refused:", gate.counts["refused"], "applied:", gate.counts["applied"])19 unchanged = snapshot(library, ".") == snapshot(CASE, ".")20 print("library unchanged:", unchanged)21 assert run.ended == "ask_user" and run.question.startswith("p-1 was not applied") and unchanged22 run.close()
python refusal-handed-back.pyended: 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
La misma reproducción de T-04 se ejecuta de nuevo, esta vez con un no y una razón. La ejecución termina como ask_user, y su último paso es la propia negativa. La pregunta que lleva el traspaso es el texto de la negativa, que dice p-1 was not applied: the person said no: the inch belongs in a later change. La razón de la persona está en ese texto, así que quien lea el traspaso ve qué se decidió y por qué. La biblioteca no cambia, y el ejemplo también lo verifica.
Regla práctica: Devuelve una negativa al modelo como resultado de herramienta que incluya la razón de la persona, y termina la ejecución como un traspaso cuya pregunta sea el mismo texto. No ignores el no, y no lo lances como una excepción que el bucle deba capturar.
El envoltorio verifica cada llamada
El control verifica lo que llega a la biblioteca a través de finish. Otra cosa puede cambiar la biblioteca: el código que ejecuta run_tests. Por eso el control envuelve cada herramienta en una guarda que compara los bytes de la biblioteca antes y después de la llamada. Si los bytes cambiaron, y el control no aplicó él mismo el cambio, la ejecución termina con library_changed, y el traspaso nombra los archivos. Esa es la séptima forma en que puede terminar una ejecución: capítulo 2 da seis desde el bucle, y la guarda añade esta. No se restaura nada, y nada más se ejecuta contra la biblioteca modificada.
1"""A test module written into the copy makes run_tests write the library. The guard sees the library's bytes change2around the run_tests call and ends the run as library_changed. It reports the file and restores nothing."""3from lib.permissions import Gate, gated, library_copy, scripted4from lib.tools import V1, Workspace56with library_copy() as library, library_copy() as scratch:7 marker = library / "unitcraft" / "marker.py"8 test_module = ("from pathlib import Path\n"9 f"Path({str(marker)!r}).write_text('MARK = 1\\n', encoding='utf-8')\n")10 gate = Gate(library, scripted())11 tools, ws = gated(V1, gate), Workspace(scratch)12 print("write test module:", tools.call(ws, "write_file", {"path": "tests/test_marker.py", "text": test_module}).text)13 result = tools.call(ws, "run_tests", {})14 print("run_tests ended:", result.end)15 print("handoff:", result.question)16 print("marker written:", marker.exists(), "| library changes counted:", gate.counts["library changed"])17 print("proposals:", gate.counts["proposals"])18 assert result.end == "library_changed" and marker.exists() and "unitcraft/marker.py" in result.question19 assert gate.counts["proposals"] == 0
python library-guard-fails-closed.pywrite 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
El script escribe un módulo de prueba en la copia. Cuando la ejecución de pruebas lo importa, el módulo escribe una marca en la biblioteca. La guarda termina la ejecución con library_changed, y el traspaso muestra the case library changed around run_tests: unitcraft/marker.py; the run stops, and nothing is restored. El archivo de marca está en la biblioteca, y no se hizo ninguna propuesta: 0. La guarda informa de la escritura después, como indica la sección sobre la copia.
La llamada a una herramienta se verifica también de una segunda forma, por su nombre.
La tabla de lib/permissions.py es la única fuente de la clase de una herramienta, y una herramienta que no aparece en ella recibe la clase never. El control rechaza esa llamada antes de que se ejecute el código propio de la herramienta, y el rechazo vuelve al modelo como texto. La descripción de la herramienta no importa aquí: una descripción que diga que una herramienta solo lee es una afirmación, y la tabla decide.
1"""A tool outside the harness's table is refused before its own code runs, even when its description says it only2reads. The refusal goes back to the model as text, and the tool's body never runs."""3from dataclasses import replace45from lib.permissions import Gate, classify, gated, library_copy, scripted6from lib.tools import V1, NoArgs, Tool, ToolResult, Workspace78ran = []91011def reset(ws, args): # stands in for any effect the table does not know about12 ran.append(1)13 return ToolResult("did something", brief="did something")141516with library_copy() as library, library_copy() as scratch:17 gate = Gate(library, scripted())18 extra = Tool("reset_library", "A read-only helper.", NoArgs, reset)19 tools = gated(replace(V1, tools=V1.tools + (extra,)), gate)20 result = tools.call(Workspace(scratch), "reset_library", {})21 print("class:", classify("reset_library"))22 print("result:", result.text)23 print("body ran:", len(ran))24 print("never calls:", gate.counts["never calls"])25 assert not ran and result.text.startswith("error:") and gate.counts["never calls"] == 1
python unknown-tool-refused.pyclass: never
result: error: reset_library is not a tool this harness runs
body ran: 0
never calls: 1
El script añade una herramienta cuya descripción dice que es un auxiliar de solo lectura, y la llama. Su clase es never, y su resultado es error: reset_library is not a tool this harness runs. Su cuerpo se ejecutó 0 veces, y el control contó 1 llamadas. Capítulo 9 aplica esta regla a las herramientas de MCP, cuyas anotaciones proceden del servidor y no son una clase.
Regla práctica: Clasifica cada herramienta en la tabla, y rechaza cualquier nombre que la tabla no liste antes de que se ejecute su cuerpo.
Las listas de permitidos no omiten la comprobación
La forma habitual de saltarse una barrera es una lista de permitidos. Una herramienta de la lista se ejecuta sin preguntar, y una barrera colocada en la pregunta queda entonces evitada para esa herramienta. En el Agent SDK, una herramienta aprobada en un paso anterior omite la función de devolución de llamada de aprobación, de modo que las comprobaciones que solo existen en esa devolución de llamada quedan evitadas para esa herramienta. La página del Agent SDK lo indica. Claude Code ordena sus reglas de otra manera: primero denegar, luego preguntar y luego permitir, y su página de permisos explica que una regla de permiso no puede crear una excepción a una regla de denegación.
Esta barrera no tiene lista de permitidos. Cada herramienta del conjunto pasa por el envoltorio, que rechaza un nombre que la tabla no incluye, y la comprobación de un cambio se encuentra en finish, donde se lee el diff. Ningún indicador de una herramienta decide si esa comprobación se ejecuta, porque ninguna herramienta queda exenta del envoltorio. Una barrera que depende de un indicador que el modelo o un servidor puede establecer no es una barrera. El capítulo 9 aplica esta regla a las herramientas MCP, y las envía por las aprobaciones de este capítulo en lugar de por una lista de permitidos.
Regla práctica: No dejes que un nombre, una descripción o un indicador de una herramienta o de su servidor decida si se ejecuta la comprobación. Coloca la comprobación en el camino que debe seguir todo cambio que hagan las herramientas. El código que ejecutan las pruebas está fuera de ese camino, como indica la sección sobre la copia, y el indicador describe la herramienta y nada más.
A lo largo del conjunto de tareas
Hasta ahora, cada ejemplo ha seguido una sola ejecución. La pregunta del caso es qué hace la puerta a lo largo de todas las ejecuciones registradas, incluidas las que no deberían cambiar nada.
1"""The 20 recorded task-set runs replayed with the gate observing, each matching its recorded ending and step count, and2the gate counting what it would have held (the four stop tasks T-16 to T-19 first). Counts only."""3from lib.case import CASE, DATA, load_tasks4from lib.permissions import Gate, library_copy, replay_task5from lib.tasks import snapshot6from lib.trace import IdCounter78import json910CHANGES = ("edit_file", "write_file")11rows = (DATA / "recorded" / "task-set" / "runs.jsonl").read_text(encoding="utf-8").splitlines()12recorded = {r["task"]: r for r in map(json.loads, rows)}13runs, gates, pendings = {}, {}, {}14with library_copy() as library:15 ids = IdCounter()16 for task in load_tasks():17 gate = Gate(library, enforce=False)18 run = replay_task(task.id, gate, library, ids=ids)19 assert (run.ended, run.steps) == (recorded[task.id]["ended"], recorded[task.id]["steps"]), task.id20 runs[task.id], gates[task.id], pendings[task.id] = run, gate, gate.settle(run.scratch)21 for tid in ("T-16", "T-17", "T-18", "T-19"):22 gate, pend, run = gates[tid], pendings[tid], runs[tid]23 refused = sum(1 for r in run.trace.records if r["tool"] in CHANGES and r["brief"].startswith("error"))24 print(f"{tid} ended: {run.ended}, steps: {run.steps}")25 print(f" change calls: {gate.counts['change calls']}, refused by the tool: {refused}")26 print(f" never-class calls: {gate.counts['never calls']}, changes in the copy at the end: {len(pend.files)}")27 print(f" held as never: {len(pend.never)}, waiting for a yes: {len(pend.files) - len(pend.never)}")28 changed = sorted(t for t in pendings if pendings[t].files)29 print("runs:", len(runs))30 print("runs with a change left in the copy:", len(changed), ", tasks:", ", ".join(changed))31 print("change calls, all runs:", sum(g.counts["change calls"] for g in gates.values()))32 print("never-class calls, all runs:", sum(g.counts["never calls"] for g in gates.values()))33 print("held as never, all runs:", sum(len(p.never) for p in pendings.values()))34 print("proposals that would wait for a yes, all runs:", sum(g.counts["waiting for a yes"] for g in gates.values()))35 print("library changed by the replays:", snapshot(library, ".") != snapshot(CASE, "."))36 assert snapshot(library, ".") == snapshot(CASE, ".") and gates["T-18"].counts["never calls"] == 137 for run in runs.values():38 run.close()
python gate-over-task-set.pyT-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 ejemplo reproduce cada ejecución registrada del conjunto de tareas a través de una puerta que observa pero no impone sus decisiones. La puerta decide como lo haría, cuenta lo que retendría y devuelve el resultado propio de cada herramienta, de modo que cada ejecución termina donde terminó en la grabación. Se comprueba que cada reproducción coincida con su final registrado y con su número de pasos, y la biblioteca queda como se encontró. Estos son recuentos de lo que la puerta haría, y eso es lo que permite probarla con seguridad antes de activar su cumplimiento obligatorio.
Las tareas de parada T-16 a T-19 intentaron cambiar archivos, y las herramientas rechazaron cada una de esas llamadas, así que ninguna de sus copias cambió. La puerta contó las llamadas. T-18 es la única tarea que intentó escribir en .github/. La puerta contó esa llamada como una llamada de clase never, 1 en total. Retuvo 0 cambios como never, porque la herramienta ya había rechazado la llamada antes de que algún cambio llegara a la copia.
Cuando una copia sí conservó un cambio, la puerta habría pedido a una persona que lo revisara. En todas las reproducciones, 5 propuestas esperarían un sí. Los recuentos muestran lo que la puerta haría con estas copias. No pueden mostrar lo que respondería una persona, y por eso los ejemplos de este capítulo usan respuestas predefinidas, y por eso un aprobador real tiene que ser una persona, o un proceso que una persona controle.
Regla práctica: Antes de poner en vigor una puerta, reproduce las ejecuciones registradas a través de ella sin imponer sus decisiones, y compara cada final y cada recuento con lo que esperabas. Un recuento que te sorprenda es un hallazgo sobre la puerta o sobre las ejecuciones, y lo resuelves antes de que alguien dependa de la puerta.
Valores por defecto de los proveedores que dejarían pasar un cambio
Varios de los fallos que se describen a continuación provienen de valores por defecto que parecen razonables. Cada uno es una afirmación que podrías creer, contrastada con lo que documentan los proveedores y con lo que hace este arnés. Las afirmaciones de los proveedores se citan con su página, y ninguna de ellas fue ejecutada para este libro.
- Una regla de permiso puede anular una de denegación. La documentación de Claude Code dice lo contrario: la denegación se evalúa primero, como señala la sección de lista de permitidos.
- El modo de omisión significa que no hay control. La documentación del SDK dice que las reglas de denegación y de confirmación siguen aplicándose en el modo de omisión, y que la lista de
allowed_toolsno lo limita. - Aprobar una vez significa aprobar para siempre. La tabla de Claude Code limita una opción de "no volver a preguntar" a un repositorio y a un comando en el caso de los comandos de shell, y a la sesión en el caso de la modificación de archivos. La página de Microsoft dice que las aprobaciones permanentes persisten en el estado de la sesión y no están ligadas a la instancia de la herramienta que las creó, de modo que una herramienta de reemplazo con el mismo nombre puede coincidir con una regla guardada.
- Cualquier respuesta sirve. El Agent Framework de Microsoft ignora una respuesta que no esté vinculada a una solicitud pendiente. Aquí la respuesta debe nombrar la propuesta y su hash, como muestra la sección de vinculación.
- Un hook que dice permitir omite las comprobaciones. La documentación del SDK dice que un hook que devuelve permitir no omite los pasos de denegación y de confirmación.
- El propio texto del modelo puede conceder la aprobación. Un resumen que diga "aprobado" o "no se necesita aprobación" no cambia nada en este arnés. El ejemplo de la clase de nunca muestra que la afirmación del resumen no modifica la negativa, porque la negativa proviene del diff.
Regla práctica: Cuando un valor por defecto de un proveedor permite que una respuesta, una marca o un hook ocupen el lugar de una comprobación, no copies ese valor por defecto. Escribe la comprobación de forma que nombre lo que aprueba: la propuesta, sus bytes y la regla que aplica. Luego verifica que una respuesta incorrecta, una copia movida y una aprobación afirmada fallen.
Lo que esta compuerta no cubre
La revisión de seguridad del código de este capítulo dejó en su lugar los límites que se indican a continuación, y esta sección es el único lugar donde se enumeran. Cada uno es un vacío del código didáctico, y ninguno queda resuelto en este capítulo.
- Código que ejecuta el agente (sección de la copia).
run_testsejecuta código escrito por el modelo con los mismos derechos que el propio arnés. El guardia informa de una escritura en la biblioteca después de que ocurra y no restaura nada. La sandbox del capítulo 7 pone límites a las pruebas y les da un entorno limpio, pero no impide escrituras en otras rutas. La defensa principal es un contenedor o una máquina virtual, y ningún ejemplo de aquí ejecuta uno. - Comprobaciones de nombres de nivel superior (F-7). La clase «never» (nunca) compara los nombres de nivel superior de
unitcraft/ytests/, y nada más profundo. Un nombre definido solo dentro de un bloque no se cuenta en ninguno de los dos árboles. Un cambio dentro del cuerpo de una función pública, y una nueva vinculación comoparse_quantity = None, esperan un sí en lugar de ser rechazados. - Excepciones del aprobador (F-8). Un aprobador que lanza una excepción termina el bucle con esa excepción, y no se aplica nada. No es un traspaso. Una herramienta que lanza un error distinto de
ToolErrortambién escapa del bucle: en una prueba sobre una copia desechable del código actual, un carácter sustituto aislado enedit_filetruncó el archivo de la copia a cero bytes y después lanzóUnicodeEncodeError. - Identificadores limitados a la ejecución (F-9). Cada compuerta numera sus propuestas desde
p-1. Por tanto, una respuesta registrada para elp-1de una compuerta coincide con elp-1de otra compuerta siempre que los dos diffs sean los mismos bytes, de modo que una respuesta reproducida desde un registro antiguo puede aprobar un cambio en una ejecución distinta. Los bytes son los que se mostraron, pero el identificador no es único entre ejecuciones. Un registro que se conserve entre ejecuciones necesita también el identificador de la ejecución. - Enlaces simbólicos (F-10). El listado de archivos de la compuerta sigue un enlace simbólico en la copia. Un enlace a un archivo situado fuera de la copia incorpora los bytes de ese archivo al diff, y un sí que cubra el diff puede entonces aplicarlos a la biblioteca como un archivo regular. La persona ve esos bytes en el diff, pero la propuesta lee un archivo que la copia no posee. La solución es omitir los enlaces, y este capítulo no la aplica.
- Lo que lee la persona. El sí cubre el diff tal como lo mostró el aprobador. Un aprobador que muestra solo una parte del texto da a la persona menos de lo que cubre el hash, y los ejemplos de este capítulo muestran el diff completo.
Regla práctica: Escribe cada límite junto al código del que procede, y nómbralo una sola vez, en un solo lugar, para que el lector pueda ver lo que la compuerta no hace antes de confiar en ella.
Decisiones que tomó este capítulo
Las decisiones que siguen son lo bastante breves para comprobarlas con los ejemplos de arriba.
- La copia es el lugar donde escriben las herramientas propias del arnés, y el arnés cambia la biblioteca por una única vía de escritura, a la que se llama después de un sí. Un contenedor o una máquina virtual es la defensa principal para el código que la ejecución lanza. La copia y la compuerta son código didáctico, y los límites abiertos explican qué dejan sin cubrir.
- La compuerta vive en
finishy lee el diff completo de la copia, no el resumen. - Las clases provienen de la tabla propia del arnés. Ni las palabras del modelo ni la descripción de una herramienta las fijan, y una herramienta que la tabla no lista se rechaza antes de que se ejecute su cuerpo.
- Un sí queda vinculado al ID de una propuesta y al hash SHA-256 de sus bytes, y la copia se vuelve a someter a hash justo antes de aplicar el cambio.
- El cuerpo propio de un finish solo se ejecuta después de un sí.
- Un no termina la ejecución como
ask_user, y la razón de la persona se convierte en la pregunta. - El arnés funciona sin interfaz, con una función de retorno. No es el modo
dontAskdel proveedor, y el libro no lo llama así.
Tres cosas quedan abiertas a propósito. El aprobador pertenece a quien llama, y los ejemplos lo programan para que funcionen sin conexión. La lista de cambios que el arnés rechaza de plano es corta, y ampliarla es una decisión de los responsables del caso, no de la compuerta. La compuerta revisa los cambios a la biblioteca y no los comandos que ejecuta el agente, tema que aborda el capítulo 7.
El arnés aplica un cambio a la biblioteca solo después de un sí, y un sí aplica únicamente los bytes que la persona vio y que se calcularon con hash. La compuerta no revisa el código que ejecuta una ejecución. El guardia detecta un cambio que ese código haga a la biblioteca y termina la ejecución, pero no lo impide; las defensas para eso están en la sección sobre la copia.
Regla práctica: Anota cada decisión que toma una compuerta junto con el ejemplo que la muestra, y enumera lo que la compuerta deja en manos de quien la llama. Una decisión sin ejemplo que la respalde es una afirmación, y el capítulo la marca como tal.
Este capítulo, en esta edición
Edición 2026.11.2Ejemplos verificados el 20 de nov de 2026Superan la prueba 12 de 12 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.2.