Paso a través de variables de entorno
El daemon se ejecuta como un proceso en segundo plano y normalmente tiene un entorno reducido. Tu terminal cuenta con el entorno completo configurado por tu perfil de shell. Hay dos formas en que las variables de entorno llegan a los subprocesos de shell generados por el agente.
reenvío zerocode (automático)
Cuando zerocode se conecta, captura el entorno de su propio proceso y lo envía al daemon como parte del handshake initialize. El daemon almacena esa instantánea en TuiRegistry, indexada por el tui_id único de zerocode. Cuando abres una nueva sesión de chat (session/new), el daemon busca la instantánea registrada por la propia conexión que realiza la llamada, nunca una indicada en la solicitud, y la clona en el ShellTool del agente. Ese clon se superpone después sobre la línea base de entorno seguro para cada subproceso de shell que el agente lanza:
cmd.env_clear()
→ Layer 1: SAFE_ENV_VARS + shell_env_passthrough (from daemon process)
→ Layer 2: zerocode's env snapshot (wins on conflict)
las variables de zerocode ganan en caso de conflicto: tu PATH, HOME y los sockets de credenciales tienen precedencia sobre lo que el daemon haya heredado. No se requiere configuración.
Por eso SSH_AUTH_SOCK funciona cuando ejecutas zerocode desde un terminal que tiene un ssh-agent en ejecución, incluso si el daemon se inició como un servicio sin agente:
sh
# El terminal tiene SSH_AUTH_SOCK configurado por ssh-agent o un token de hardware (YubiKey, etc.)
echo $SSH_AUTH_SOCK
# /run/user/1000/gnupg/S.gpg-agent.ssh
# El daemon se inició como un servicio de systemd, sin SSH_AUTH_SOCK en su entorno.
# zerocode forwards its env at connect time, so any shell command the agent
# las ejecuciones (git push, ssh, gpg-sign) obtienen SSH_AUTH_SOCK desde tu terminal.
zerocode envía su entorno completo en cada conexión, pero el demonio solo conserva la instantánea donde es de confianza: en una conexión local con un principal de nivel operador (el socket Unix o la tubería con nombre de Windows), que es el flujo del IDE local descrito anteriormente. En una conexión WSS, la instantánea describe el host del cliente y no el del demonio, y un principal del roster con un perfil de permisos no debe poder decidir qué se ejecuta como cuenta del demonio. Por eso, en ambos casos, el demonio descarta la instantánea en initialize, registra que lo hizo, y los subprocesos de shell de la sesión solo ven la Capa 1. Usa shell_env_passthrough en el perfil de riesgo para suministrar variables concretas del propio entorno del demonio en ese caso.
Múltiples clientes conectados: sin sobrescritura entre sesiones
Cada instancia de zerocode obtiene un tui_id único (tui_ + 8 caracteres hexadecimales aleatorios). El registro es un HashMap<tui_id → TuiEntry>, y las entradas son completamente independientes:
TuiRegistry
├── "tui_a1b2c3d4" → { env: { PATH: "/home/alice/…", VIRTUAL_ENV: "…" } }
├── "tui_beef0042" → { env: { PATH: "/home/bob/…" } }
└── "tui_cafe1234" → { env: { PATH: "/opt/pyenv/…" } }
Cuando zerocode tui_a1b2c3d4 abre una sesión, solo se clona y utiliza su instantánea de entorno. Los entornos de los demás clientes nunca se modifican. Concretamente:
| Escenario | Resultado |
|---|---|
Dos clientes abiertos desde shells diferentes con distintos PATHs | Cada sesión obtiene su propio PATH; ninguna afecta a la otra |
El cliente A tiene VIRTUAL_ENV configurado; el cliente B no | Solo las sesiones del Cliente A ven VIRTUAL_ENV |
| El Cliente A se desconecta mientras la sesión del Cliente B está en ejecución | El cliente B no se ve afectado; el env fue clonado al crear la sesión |
| Cliente B adjunta una sesión que creó el Cliente A mientras dicha sesión sigue activa | Rechazado a menos que ambos clientes reenvíen exactamente el mismo entorno; las variables por terminal, como TERM_SESSION_ID, suelen diferir, así que inicia una nueva sesión en su lugar |
El cliente A se vuelve a conectar con el mismo tui_id | La entrada antigua se elimina, la nueva entrada con un entorno actualizado se registra; las sesiones que ya están en ejecución conservan su clon original |
El último punto es importante: el registro entrega a la sesión un clon, no una referencia. Una vez creada, la sesión es dueña de su instantánea del entorno. Las reconexiones o desconexiones del cliente de origen no tienen ningún efecto sobre las sesiones en ejecución.
Paso directo del perfil de riesgo (lista de permitidos explícita)
shell_env_passthrough en un perfil de riesgo controla qué variables del entorno de proceso del propio daemon se pasan a los subprocesos de shell. Esto es útil cuando quieres que ciertas variables específicas estén disponibles independientemente de si zerocode está conectado, por ejemplo en un servidor headless donde el propio daemon tiene las variables configuradas.
Los subagentes no pueden ampliar esta lista más allá de lo que permite la política del padre: agregar una var que no esté presente en la lista del padre se rechaza como una escalación de política.