環境変数のパススルー
デーモンはバックグラウンドプロセスとして実行され、通常は最小限の環境しか持ちません。ターミナルは、シェルプロファイルによって設定された完全な環境を持っています。エージェントによって生成されるシェルサブプロセスに環境変数が渡される方法は2つあります。
zerocode 転送（自動）
zerocode が接続すると、自身のプロセス環境変数を取得し、initialize ハンドシェイクの一部としてデーモンに送信します。デーモンはそのスナップショットを、zerocode の一意な tui_id をキーとして TuiRegistry に保存します。新しいチャットセッション（session/new）を開くと、デーモンはリクエストで指定された名前のものではなく、呼び出し元の接続自身が登録したスナップショットを検索し、エージェントの 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は毎回の接続で完全な環境変数を送信しますが、デーモンがその環境のスナップショットを保持するのは信頼できる場合に限られます。具体的には、ローカル接続(Unixソケットまたは Windows の名前付きパイプ)上のオペレータレベルのプリンシパルで、これは上記で説明したローカルIDEのフローです。WSS接続の場合、スナップショットはデーモン側ではなくクライアントのホストを表すものであり、パーミッションプロファイルを持つrosterプリンシパルがデーモンアカウントとして実行される内容を決めることがあってはなりません。そのため、どちらの場合もデーモンはinitializeの時点でスナップショットを破棄し、その旨をログに記録します。そのセッションのシェルサブプロセスはLayer 1のみを参照します。そこでデーモン自身の環境から特定の変数を渡すには、リスクプロファイルでshell_env_passthroughを使用してください。
複数の接続クライアント: セッション間での競合上書きなし
各 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が作成したセッションがまだ有効な間に、クライアントBがそのセッションにアタッチする | |Both clients must forward exactly the same environment; otherwise it is refused. Per-terminal variables such as TERM_SESSION_ID usually differ, so start a new session instead. |
Wait, that is English output; I need to translate to Japanese.
両方のクライアントが完全に同じ環境変数を転送していない場合は拒否されます。TERM_SESSION_ID などのターミナルごとの変数は通常異なるため、代わりに新しいセッションを開始してください。|
|クライアント A が同じ tui_id で再接続します|古いエントリは削除され、新しい環境を持つ新しいエントリが登録されます。既に実行中のセッションは元のクローンを保持します。|
クローンであり、参照ではありません。セッションが作成されると、そのセッションは環境変数のスナップショットを所有します。元のクライアントの再接続や切断は、実行中のセッションに影響しません。
リスクプロファイルのパススルー（明示的な許可リスト）
リスクプロファイルの shell_env_passthrough は、デーモン自身のプロセス環境 のどの変数をシェルサブプロセスに渡すかを制御します。これは、zerocode が接続されているかどうかに関わらず特定の変数を利用可能にしたい場合に便利です。例えば、デーモン自体に変数が設定されているヘッドレスサーバーなどです。
サブエージェントは、親ポリシーが許可する範囲を超えてこのリストを拡張することはできません。親のリストに存在しない変数を追加すると、ポリシーの権限昇格として拒否されます。