环境变量透传
守护进程作为后台进程运行，通常拥有精简的环境。你的终端则拥有由 shell 配置文件设置的完整环境。环境变量有两种方式可以传递给由 agent 派生的 shell 子进程。
zerocode 转发（自动）
当 zerocode 连接时，它会捕获自身的进程环境，并在 initialize 握手过程中将其发送给守护进程。守护进程将该快照存入 TuiRegistry，以 zerocode 唯一的 tui_id 作为键。当你新建聊天会话（session/new）时，守护进程只会查找发起该请求的连接自身注册的快照，而不会使用请求中指定的快照，并将其克隆到智能体的 ShellTool 中。随后，该克隆会叠加在安全环境基线之上，应用于智能体派生的每个 shell 子进程：
cmd.env_clear()
→ Layer 1: SAFE_ENV_VARS + shell_env_passthrough (from daemon process)
→ Layer 2: zerocode's env snapshot (wins on conflict)
zerocode 变量在冲突时优先：你的 PATH、HOME 和凭据套接字会优先于守护进程所继承的任何值。无需任何配置。
这就是为什么当你从运行着 ssh-agent 的终端启动 zerocode 时 SSH_AUTH_SOCK 能够生效，即使该守护进程是作为服务启动且没有 agent：
sh
# 终端已通过 ssh-agent 或硬件令牌（YubiKey 等）设置 SSH_AUTH_SOCK
echo $SSH_AUTH_SOCK
# /run/user/1000/gnupg/S.gpg-agent.ssh
# 守护进程作为 systemd 服务启动，其环境中没有 SSH_AUTH_SOCK。
# zerocode forwards its env at connect time, so any shell command the agent
# runs（git push、ssh、gpg-sign）会从你的终端获取 SSH_AUTH_SOCK。
zerocode 会在每次连接时发送其完整环境，但守护进程只在可信的情况下保留该快照：即本地连接（Unix 套接字或 Windows 命名管道）上的运维级主体，也就是上文所述的本地 IDE 流程。在 WSS 连接上，该快照描述的是客户端主机而非守护进程所在主机。而且，带有权限配置文件的 roster 主体不得决定以守护进程账户运行什么内容。因此在这两种情况下，守护进程都会在 initialize 时丢弃该快照并记录日志，该会话的 shell 子进程将只能看到第 1 层（Layer 1）。若需在此类情况下提供特定变量，请在风险配置文件中使用 shell_env_passthrough，以从守护进程自身的环境中提取这些变量。
多客户端连接：避免跨会话相互覆盖
每个 zerocode 实例都会获得一个唯一的 tui_id（tui_ + 8 个随机十六进制字符）。该注册表是一个 HashMap<tui_id → TuiEntry>，各个条目之间完全独立：
TuiRegistry
├── "tui_a1b2c3d4" → { env: { PATH: "/home/alice/…", VIRTUAL_ENV: "…" } }
├── "tui_beef0042" → { env: { PATH: "/home/bob/…" } }
└── "tui_cafe1234" → { env: { PATH: "/opt/pyenv/…" } }
当 zerocode tui_a1b2c3d4 打开一个会话时，只会克隆并使用 它自己的 环境变量快照。其他客户端的环境变量永远不会被修改。具体来说：
| 场景 | 结果 |
|---|---|
从具有不同 PATH 的不同 shell 中打开两个客户端 | 每个会话都有各自的 PATH，互不影响 |
客户端 A 设置了 VIRTUAL_ENV；客户端 B 没有 | 只有来自 Client A 的会话才能看到 VIRTUAL_ENV |
| 客户端 A 在客户端 B 的会话运行时断开连接 | 客户端 B 不受影响；env 在会话创建时已克隆 |
| 客户端 B 在会话仍处于活动状态时，附加到客户端 A 创建的会话 | 拒绝执行，除非两个客户端转发完全相同的环境变量；诸如 TERM_SESSION_ID 之类的单终端变量通常各不相同，因此请改为启动新会话。 |
客户端 A 使用相同的 tui_id 重新连接 | 旧条目被移除，注册了带有新环境的新条目；已经运行的会话保留其原始克隆 |
最后一点很重要：注册表交给会话的是一个克隆，而不是引用。会话创建后即拥有其环境快照。发起会话的客户端重连或断开，对正在运行的会话没有影响。
风险配置直通（显式允许列表）
风险配置文件中的 shell_env_passthrough 用于控制将 守护进程自身的进程环境 中的哪些变量传递给 shell 子进程。当你希望无论 zerocode 是否已连接都能使用特定变量时，这非常有用，例如在守护进程自身已设置这些变量的无头服务器上。
子代理无法将此列表扩展到超出父级策略所允许的范围：添加父级列表中不存在的变量会被作为策略提权而拒绝。