環境変数のパススルー
デーモンはバックグラウンドプロセスとして実行され、通常は最小限の環境しか持ちません。ターミナルは、シェルプロファイルによって設定された完全な環境を持っています。エージェントによって生成されるシェルサブプロセスに環境変数が渡される方法は2つあります。
zerocode 転送（自動）
zerocode が接続すると、自身のプロセス環境をキャプチャし、initialize ハンドシェイクの一部としてデーモンに送信します。デーモンはそのスナップショットを zerocode の一意の tui_id をキーにして TuiRegistry に保存します。新しいチャットセッション（session/new）を開くと、デーモンは zerocode のスナップショットを検索し、それをエージェントの ShellTool にクローンします。このクローンは、エージェントが生成するすべてのシェルサブプロセスにおいて、safe-env ベースラインの上にオーバーレイされます。
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 が機能する理由です:
sh
# ターミナルに ssh-agent またはハードウェアトークン（YubiKey など）によって `SSH_AUTH_SOCK` が設定されています
echo $SSH_AUTH_SOCK
# /run/user/1000/gnupg/S.gpg-agent.ssh
# Daemon は systemd サービスとして起動されており、その環境に SSH_AUTH_SOCK が存在しません。
# zerocode forwards its env at connect time, so any shell command the agent
# 実行(git push、ssh、gpg-sign)は、ターミナルから SSH_AUTH_SOCK を取得します。
zerocode は環境全体を送信します。共有またはリモートのデーモンでこれが懸念される場合は、専用のユーザーアカウントで WSS を使用してください。
複数の接続クライアント: セッション間での競合上書きなし
各 zerocode インスタンスには一意の tui_id（tui_ + ランダムな 16 進数 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 がセッションを開くと、その 環境スナップショットのみがクローンされて使用されます。他のクライアントの環境が変更されることはありません。具体的には:
| シナリオ | Result |
|---|---|
異なるPATHを持つ別々のシェルから2つのクライアントが開いている | セッションごとに独自の PATH が割り当てられ、互いに影響を与えません |
クライアント A には VIRTUAL_ENV が設定されており、クライアント B には設定されていません | クライアント A のセッションのみが VIRTUAL_ENV を参照できます |
| クライアント B のセッション実行中にクライアント A が切断する | クライアント B は影響を受けません。env はセッション作成時にクローンされています |
クライアント A が同じ tui_id で再接続します | 古いエントリは削除され、新しい環境を持つ新しいエントリが登録されます。既に実行中のセッションは元のクローンを保持します。 |
最後の点が重要です。get_env は参照ではなくクローンを返します。セッションが作成されると、それは自身の環境スナップショットを所有します。元のクライアントの再接続や切断は、実行中のセッションには影響しません。
リスクプロファイルのパススルー（明示的な許可リスト）
リスクプロファイルの shell_env_passthrough は、デーモン自身のプロセス環境 のどの変数をシェルサブプロセスに渡すかを制御します。これは、zerocode が接続されているかどうかに関わらず特定の変数を利用可能にしたい場合に便利です。例えば、デーモン自体に変数が設定されているヘッドレスサーバーなどです。
サブエージェントは、親ポリシーが許可する範囲を超えてこのリストを拡張することはできません。親のリストに存在しない変数を追加すると、ポリシーの権限昇格として拒否されます。