@team-agent/installer 0.5.111 → 0.5.113

package/crates/team-agent/src/messaging/tests/runtime.rs

@@ -1090,52 +1090,6 @@ fn collect_rejects_message_scoped_result_without_matching_recipient() {
     );
 }
 
-#[test]
-fn allow_peer_talk_records_bidirectional_allowlist_and_event() {
-    let ws = tmp_ws("allowpeer");
-    let out = allow_peer_talk(&ws, "alice", "bob").unwrap();
-    assert_eq!(out.get("ok").and_then(|v| v.as_bool()), Some(true));
-    assert_eq!(out.get("a").and_then(|v| v.as_str()), Some("alice"));
-    assert_eq!(out.get("b").and_then(|v| v.as_str()), Some("bob"));
-    assert_eq!(
-        out.get("status").and_then(|v| v.as_str()),
-        Some("compat_noop")
-    );
-    assert_eq!(
-        out.get("reason").and_then(|v| v.as_str()),
-        Some("team_scoped_peer_messages_enabled")
-    );
-
-    let store = store_for(&ws);
-    let conn = seed_conn(&store);
-    let rows = conn
-        .prepare("select a, b from peer_allowlist order by a, b")
-        .unwrap()
-        .query_map([], |row| {
-            Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
-        })
-        .unwrap()
-        .collect::<Result<Vec<_>, _>>()
-        .unwrap();
-    assert_eq!(
-        rows,
-        vec![
-            ("alice".to_string(), "bob".to_string()),
-            ("bob".to_string(), "alice".to_string()),
-        ]
-    );
-
-    let events = EventLog::new(&ws).tail(10).unwrap();
-    let event = events
-        .iter()
-        .find(|event| {
-            event.get("event").and_then(|v| v.as_str()) == Some("communication.peer_allowed")
-        })
-        .expect("communication.peer_allowed event");
-    assert_eq!(event.get("a").and_then(|v| v.as_str()), Some("alice"));
-    assert_eq!(event.get("b").and_then(|v| v.as_str()), Some("bob"));
-}
-
 // ════════════════════════════════════════════════════════════════════════
 // GROUP R — run_comms_selftest: §84 / MUST-NOT-13 zero-provider-SDK gate.
 // diagnose/comms.py:21-47. The whole point: assert zero provider client calls.

package/crates/team-agent/src/provider/adapter.rs

@@ -300,6 +300,10 @@ pub fn get_adapter(p: Provider) -> Box<dyn ProviderAdapter> {
     Box::new(BasicProviderAdapter { provider: p })
 }
 
+#[cfg(test)]
+#[path = "tests/command_helpers.rs"]
+mod command_helpers_tests;
+
 #[derive(Debug, Clone, Copy)]
 pub(crate) struct BasicProviderAdapter {
     provider: Provider,
@@ -480,22 +484,13 @@ impl ProviderAdapter for BasicProviderAdapter {
                 Ok(argv)
             }
             Provider::Grok => Ok(grok_launch_command(
-                self,
-                auth_mode,
-                mcp_config,
                 system_prompt,
                 model,
                 dangerously_skip_permissions,
             )?),
             Provider::CursorAgent => Ok(cursor_agent_base_command(
-                self,
-                auth_mode,
-                mcp_config,
-                system_prompt,
                 model,
                 dangerously_skip_permissions,
-                false,
-                None,
             )?),
             Provider::Pi => Err(ProviderError::Command(
                 "Pi commands require the shared lifecycle materializer".to_string(),
@@ -596,14 +591,9 @@ impl ProviderAdapter for BasicProviderAdapter {
                 // never written and restart could not resume.
                 let expected = next_session_token();
                 let mut argv = grok_base_command(
-                    self,
-                    ctx.auth_mode,
-                    ctx.mcp_config,
                     ctx.system_prompt,
                     ctx.model,
                     ctx.dangerously_skip_permissions,
-                    ctx.profile_launch
-                        .is_some_and(|profile| profile.managed_mcp_config),
                     ctx.effort,
                 )?;
                 argv.push("--session-id".to_string());
@@ -637,15 +627,8 @@ impl ProviderAdapter for BasicProviderAdapter {
                 // U-01 create-chat 无登录超时；禁止发明 --session-id。
                 // pending 只能是 CLI chatId，本拍不造假 uuid。
                 let argv = cursor_agent_base_command(
-                    self,
-                    ctx.auth_mode,
-                    ctx.mcp_config,
-                    ctx.system_prompt,
                     ctx.model,
                     ctx.dangerously_skip_permissions,
-                    ctx.profile_launch
-                        .is_some_and(|profile| profile.managed_mcp_config),
-                    ctx.effort,
                 )?;
                 Ok(CommandPlan {
                     argv,
@@ -816,7 +799,7 @@ impl ProviderAdapter for BasicProviderAdapter {
             // copilot --resume 接受 id|name)。
             Provider::Copilot => {
                 let mut argv =
-                    copilot_base_command_resume(auth_mode, mcp_config, system_prompt, model, dangerously_skip_permissions);
+                    copilot_base_command(auth_mode, mcp_config, system_prompt, model, dangerously_skip_permissions);
                 argv.push("--resume".to_string());
                 argv.push(session_id.as_str().to_string());
                 Ok(argv)
@@ -824,13 +807,9 @@ impl ProviderAdapter for BasicProviderAdapter {
             // Grok resume: base + `--resume <id>` (grok -r/--resume 接受 id|title)。
             Provider::Grok => {
                 let mut argv = grok_base_command(
-                    self,
-                    auth_mode,
-                    mcp_config,
                     system_prompt,
                     model,
                     dangerously_skip_permissions,
-                    false,
                     None,
                 )?;
                 argv.push("--resume".to_string());
@@ -839,16 +818,7 @@ impl ProviderAdapter for BasicProviderAdapter {
             }
             // Cursor resume: base + `--resume <chatId>`。
             Provider::CursorAgent => {
-                let mut argv = cursor_agent_base_command(
-                    self,
-                    auth_mode,
-                    mcp_config,
-                    system_prompt,
-                    model,
-                    dangerously_skip_permissions,
-                    false,
-                    None,
-                )?;
+                let mut argv = cursor_agent_base_command(model, dangerously_skip_permissions)?;
                 // Put --resume immediately after `agent` so the CLI treats it as
                 // the session mode rather than a trailing flag after --workspace.
                 argv.insert(1, "--resume".to_string());
@@ -941,14 +911,9 @@ impl ProviderAdapter for BasicProviderAdapter {
                     ));
                 };
                 let mut argv = grok_base_command(
-                    self,
-                    ctx.auth_mode,
-                    ctx.mcp_config,
                     ctx.system_prompt,
                     ctx.model,
                     ctx.dangerously_skip_permissions,
-                    ctx.profile_launch
-                        .is_some_and(|profile| profile.managed_mcp_config),
                     ctx.effort,
                 )?;
                 argv.push("--resume".to_string());
@@ -968,15 +933,8 @@ impl ProviderAdapter for BasicProviderAdapter {
                     ));
                 }
                 let mut argv = cursor_agent_base_command(
-                    self,
-                    ctx.auth_mode,
-                    ctx.mcp_config,
-                    ctx.system_prompt,
                     ctx.model,
                     ctx.dangerously_skip_permissions,
-                    ctx.profile_launch
-                        .is_some_and(|profile| profile.managed_mcp_config),
-                    ctx.effort,
                 )?;
                 argv.push("--resume".to_string());
                 argv.push(raw.to_string());
@@ -1067,13 +1025,9 @@ impl ProviderAdapter for BasicProviderAdapter {
             // (grok help: --fork-session 需配合 --resume/--continue)。
             Provider::Grok => {
                 let mut argv = grok_base_command(
-                    self,
-                    auth_mode,
-                    mcp_config,
                     system_prompt,
                     model,
                     dangerously_skip_permissions,
-                    false,
                     None,
                 )?;
                 argv.push("--session-id".to_string());
@@ -1191,7 +1145,7 @@ impl ProviderAdapter for BasicProviderAdapter {
                     .ok_or_else(|| {
                         ProviderError::Command("copilot fork root was not materialized".to_string())
                     })?;
-                let mut argv = copilot_base_command_resume(
+                let mut argv = copilot_base_command(
                     ctx.auth_mode,
                     ctx.mcp_config,
                     ctx.system_prompt,
@@ -1214,14 +1168,9 @@ impl ProviderAdapter for BasicProviderAdapter {
                     ));
                 };
                 let mut argv = grok_base_command(
-                    self,
-                    ctx.auth_mode,
-                    ctx.mcp_config,
                     ctx.system_prompt,
                     ctx.model,
                     ctx.dangerously_skip_permissions,
-                    ctx.profile_launch
-                        .is_some_and(|profile| profile.managed_mcp_config),
                     ctx.effort,
                 )?;
                 argv.push("--session-id".to_string());
@@ -1405,7 +1354,7 @@ pub(crate) fn json_inline(value: &serde_json::Value) -> String {
 // the extracted base-command functions, not directly by this file.
 use super::adapters::claude::{claude_base_command, claude_launch_command};
 use super::adapters::codex::codex_base_command;
-use super::adapters::copilot::{copilot_base_command, copilot_base_command_resume};
+use super::adapters::copilot::copilot_base_command;
 use super::adapters::cursor_agent::cursor_agent_base_command;
 use super::adapters::fake::fake_worker_command;
 use super::adapters::grok::{grok_base_command, grok_launch_command};

package/crates/team-agent/src/provider/adapters/claude.rs

@@ -11,6 +11,7 @@
 use crate::model::enums::{AuthMode, Provider};
 use crate::provider::adapter::{next_session_token, prompt_needs_native_mcp, BasicProviderAdapter};
 use crate::provider::{McpConfig, ProviderAdapter, ProviderError};
+use crate::provider::command_helpers::{append_opt_pair, append_pair};
 
 pub(crate) fn claude_launch_command(
     adapter: &BasicProviderAdapter,
@@ -30,8 +31,7 @@ pub(crate) fn claude_launch_command(
         false,
         None,
     )?;
-    argv.push("--session-id".to_string());
-    argv.push(next_session_token());
+    append_pair(&mut argv, "--session-id", next_session_token());
     Ok(argv)
 }
 
@@ -54,21 +54,14 @@ pub(crate) fn claude_base_command(
             .expect("claude provider must define a bypass flag");
         argv.push(flag.to_string());
     } else {
-        argv.push("--permission-mode".to_string());
-        argv.push("default".to_string());
-    }
-    if let Some(model) = model {
-        argv.push("--model".to_string());
-        argv.push(model.to_string());
+        append_pair(&mut argv, "--permission-mode", "default");
     }
+    append_opt_pair(&mut argv, "--model", model);
     if let Some(effort) = effort {
         argv.push("--effort".to_string());
         argv.push(effort.as_str().to_string());
     }
-    if let Some(prompt) = system_prompt {
-        argv.push("--append-system-prompt".to_string());
-        argv.push(prompt.to_string());
-    }
+    append_opt_pair(&mut argv, "--append-system-prompt", system_prompt);
     if !managed_mcp_config
         && (mcp_config.is_some()
             || auth_mode == AuthMode::CompatibleApi
@@ -79,8 +72,7 @@ pub(crate) fn claude_base_command(
         } else {
             serde_json::json!({"mcpServers": adapter.mcp_config(auth_mode)?.raw})
         };
-        argv.push("--mcp-config".to_string());
-        argv.push(raw.to_string());
+        append_pair(&mut argv, "--mcp-config", raw.to_string());
     }
     Ok(argv)
 }

package/crates/team-agent/src/provider/adapters/codex.rs

@@ -8,6 +8,7 @@
 
 use crate::model::enums::AuthMode;
 use crate::provider::adapter::json_inline;
+use crate::provider::command_helpers::{append_opt_pair, append_pair};
 use crate::provider::{McpConfig, ProviderCommandOverrides};
 
 pub(crate) fn codex_base_command(
@@ -36,24 +37,17 @@ pub(crate) fn codex_base_command(
         "--disable".to_string(),
         "apps".to_string(),
     ]);
-    if let Some(profile) = overrides.and_then(|o| o.codex_profile.as_deref()) {
-        argv.push("--profile".to_string());
-        argv.push(profile.to_string());
-    }
+    append_opt_pair(&mut argv, "--profile", overrides.and_then(|o| o.codex_profile.as_deref()));
     if dangerously_skip_permissions {
         // 0.5.66 bypass 单源:flag 由 provider_bypass_flag 表供给。
         let flag = crate::provider::bypass_flags::provider_bypass_flag(crate::model::enums::Provider::Codex)
             .expect("codex provider must define a bypass flag");
         argv.push(flag.to_string());
     }
-    if let Some(model) = model {
-        argv.push("--model".to_string());
-        argv.push(model.to_string());
-    }
+    append_opt_pair(&mut argv, "--model", model);
     if let Some(overrides) = overrides {
         for config in &overrides.codex_config {
-            argv.push("-c".to_string());
-            argv.push(config.clone());
+            append_pair(&mut argv, "-c", config.clone());
         }
     }
     if let Some(effort) = effort {
@@ -66,8 +60,7 @@ pub(crate) fn codex_base_command(
             .replace('\\', "\\\\")
             .replace('"', "\\\"")
             .replace('\n', "\\n");
-        argv.push("-c".to_string());
-        argv.push(format!("developer_instructions=\"{escaped}\""));
+        append_pair(&mut argv, "-c", format!("developer_instructions=\"{escaped}\""));
     }
     if let Some(config) = mcp_config {
         append_codex_mcp_overrides(&mut argv, &config.raw);
@@ -91,8 +84,7 @@ pub(crate) fn append_codex_mcp_overrides(argv: &mut Vec<String>, raw: &serde_jso
             if key == "env" {
                 if let Some(env) = value.as_object() {
                     for (env_key, env_value) in env {
-                        argv.push("-c".to_string());
-                        argv.push(format!(
+                        append_pair(argv, "-c", format!(
                             "mcp_servers.{name}.env.{env_key}={}",
                             json_inline(env_value)
                         ));
@@ -100,12 +92,10 @@ pub(crate) fn append_codex_mcp_overrides(argv: &mut Vec<String>, raw: &serde_jso
                 }
                 continue;
             }
-            argv.push("-c".to_string());
-            argv.push(format!("mcp_servers.{name}.{key}={}", json_inline(value)));
+            append_pair(argv, "-c", format!("mcp_servers.{name}.{key}={}", json_inline(value)));
         }
         // Every MCP server gets a 600s tool timeout so long-running
         // team_orchestrator calls (report_result etc.) survive the codex default.
-        argv.push("-c".to_string());
-        argv.push(format!("mcp_servers.{name}.tool_timeout_sec=600.0"));
+        append_pair(argv, "-c", format!("mcp_servers.{name}.tool_timeout_sec=600.0"));
     }
 }

package/crates/team-agent/src/provider/adapters/copilot.rs

@@ -3,12 +3,13 @@
 //!
 //! Extracted from `provider/adapter.rs` (0.4.x decoupling step 2). Pure
 //! extraction — byte-identical to the original inline forms. Scope kept
-//! small: base command + resume + MCP type→transport
+//! small: base command + MCP type→transport
 //! translation. Auth hint (`copilot_auth_hint`) stays in `adapter.rs`;
 //! session-store scanning lives under `provider/session_scan/copilot.rs`.
 
 use crate::model::enums::AuthMode;
 use crate::provider::McpConfig;
+use crate::provider::command_helpers::{append_opt_pair, append_pair};
 
 pub(crate) fn copilot_base_command(
     auth_mode: AuthMode,
@@ -35,18 +36,13 @@ pub(crate) fn copilot_base_command(
         argv.push(flag.to_string());
     }
     // mcp_team ∈ canonical → approval-free (whole-server pattern).
-    argv.push("--allow-tool".to_string());
-    argv.push("team_orchestrator".to_string());
-    if let Some(model) = model {
-        argv.push("--model".to_string());
-        argv.push(model.to_string());
-    }
+    append_pair(&mut argv, "--allow-tool", "team_orchestrator");
+    append_opt_pair(&mut argv, "--model", model);
     if let Some(config) = mcp_config {
         // Copilot mcp config schema field is `transport` (stdio|http|sse),
         // not the canonical `type`. McpConfig.raw is canonical; only copilot
         // translates type→transport for --additional-mcp-config.
-        argv.push("--additional-mcp-config".to_string());
-        argv.push(copilot_translate_mcp_config(&config.raw).to_string());
+        append_pair(&mut argv, "--additional-mcp-config", copilot_translate_mcp_config(&config.raw).to_string());
     }
     argv
 }
@@ -77,16 +73,3 @@ pub(crate) fn copilot_translate_mcp_config(raw: &serde_json::Value) -> serde_jso
     }
     serde_json::Value::Object(translated)
 }
-
-/// Resume path = base + `--resume <sid>` (drop --session-id); kept separate
-/// to avoid the plan accidentally emitting --session-id and --resume in the
-/// same frame.
-pub(crate) fn copilot_base_command_resume(
-    auth_mode: AuthMode,
-    mcp_config: Option<&McpConfig>,
-    system_prompt: Option<&str>,
-    model: Option<&str>,
-    dangerously_skip_permissions: bool,
-) -> Vec<String> {
-    copilot_base_command(auth_mode, mcp_config, system_prompt, model, dangerously_skip_permissions)
-}

package/crates/team-agent/src/provider/adapters/cursor_agent.rs

@@ -3,7 +3,7 @@
 //! contract:
 //!   provides:
 //!     - name: cursor_agent_base_command
-//!       what: 只组已实测文档化 flag；mcp_config 不入 argv，由 launch overlay 写盘
+//!       what: 只组已实测文档化 flag；MCP 由 launch overlay 写盘
 //! boundary:
 //!   - 不调未文档化 flag（--system-prompt / --allowed-tools）
 //!   - 不写 grok 那种 cwd 独占闸
@@ -22,60 +22,23 @@
 //! 随时可能消失。可以在注释里记录，代码里不许调。
 //! `--allowed-tools` 正反行为未验证，不写「支持工具白名单」。
 
-use crate::model::enums::AuthMode;
-use crate::provider::adapter::BasicProviderAdapter;
-use crate::provider::{McpConfig, ProviderError};
-
-pub(crate) fn cursor_agent_launch_command(
-    adapter: &BasicProviderAdapter,
-    auth_mode: AuthMode,
-    mcp_config: Option<&McpConfig>,
-    system_prompt: Option<&str>,
-    model: Option<&str>,
-    dangerously_skip_permissions: bool,
-) -> Result<Vec<String>, ProviderError> {
-    cursor_agent_base_command(
-        adapter,
-        auth_mode,
-        mcp_config,
-        system_prompt,
-        model,
-        dangerously_skip_permissions,
-        false,
-        None,
-    )
-}
+use crate::provider::ProviderError;
+use crate::provider::command_helpers::{append_opt_pair, append_pair};
 
 pub(crate) fn cursor_agent_base_command(
-    adapter: &BasicProviderAdapter,
-    auth_mode: AuthMode,
-    mcp_config: Option<&McpConfig>,
-    system_prompt: Option<&str>,
     model: Option<&str>,
     dangerously_skip_permissions: bool,
-    managed_mcp_config: bool,
-    effort: Option<crate::model::enums::ProviderEffort>,
 ) -> Result<Vec<String>, ProviderError> {
     let mut argv = vec!["agent".to_string()];
     if dangerously_skip_permissions {
         // Explicit bypass also opts into Cursor's trusted, unsandboxed launch.
         argv.push("--trust".to_string());
-        argv.push("--sandbox".to_string());
-        argv.push("disabled".to_string());
+        append_pair(&mut argv, "--sandbox", "disabled");
         argv.push("--force".to_string());
     }
-    if let Some(model) = model {
-        argv.push("--model".to_string());
-        argv.push(model.to_string());
-    }
-    // Cursor `--effort` flag 不存在；框架在调用方丢掉 effort。绝不发明 flag。
-    let _ = effort;
-    // system_prompt 不入 argv（help 无 --rules / --append-system-prompt）。
-    // launch 写 `<workspace>/.cursor/rules/team-agent-role-<agent_id>.mdc`。
-    // mcp_config 也不入 argv（无 --mcp-config）。launch 写 `.cursor/mcp.json`
-    // 并 `agent mcp enable team_orchestrator`。这里收下以免静默丢弃。
-    let _ = (adapter, auth_mode, mcp_config, managed_mcp_config, system_prompt);
-    argv.push("--workspace".to_string());
-    argv.push("{workspace}".to_string());
+    append_opt_pair(&mut argv, "--model", model);
+    // Cursor has no `--effort`, system-prompt, or MCP config flag.
+    // Launch materializes role rules and the `.cursor/mcp.json` overlay.
+    append_pair(&mut argv, "--workspace", "{workspace}");
     Ok(argv)
 }

package/crates/team-agent/src/provider/adapters/grok.rs

@@ -30,62 +30,38 @@
 //! → `native_mcp_config: false`; MCP reaches the worker via launch-path
 //! `<cwd>/.grok/config.toml` (`apply_grok_mcp_overlay`).
 
-use crate::model::enums::AuthMode;
-use crate::provider::adapter::{next_session_token, BasicProviderAdapter};
-use crate::provider::{McpConfig, ProviderError};
+use crate::provider::adapter::next_session_token;
+use crate::provider::ProviderError;
+use crate::provider::command_helpers::{append_opt_pair, append_pair};
 
 pub(crate) fn grok_launch_command(
-    adapter: &BasicProviderAdapter,
-    auth_mode: AuthMode,
-    mcp_config: Option<&McpConfig>,
     system_prompt: Option<&str>,
     model: Option<&str>,
     dangerously_skip_permissions: bool,
 ) -> Result<Vec<String>, ProviderError> {
-    let mut argv = grok_base_command(
-        adapter,
-        auth_mode,
-        mcp_config,
-        system_prompt,
-        model,
-        dangerously_skip_permissions,
-        false,
-        None,
-    )?;
-    argv.push("--session-id".to_string());
-    argv.push(next_session_token());
+    let mut argv = grok_base_command(system_prompt, model, dangerously_skip_permissions, None)?;
+    append_pair(&mut argv, "--session-id", next_session_token());
     Ok(argv)
 }
 
 pub(crate) fn grok_base_command(
-    adapter: &BasicProviderAdapter,
-    auth_mode: AuthMode,
-    mcp_config: Option<&McpConfig>,
     system_prompt: Option<&str>,
     model: Option<&str>,
     dangerously_skip_permissions: bool,
-    managed_mcp_config: bool,
     effort: Option<crate::model::enums::ProviderEffort>,
 ) -> Result<Vec<String>, ProviderError> {
     let mut argv = vec!["grok".to_string()];
     if dangerously_skip_permissions {
         argv.push("--always-approve".to_string());
     }
-    if let Some(model) = model.map(str::trim).filter(|value| !value.is_empty()) {
-        argv.push("--model".to_string());
-        argv.push(model.to_string());
-    }
+    append_opt_pair(&mut argv, "--model", model.map(str::trim).filter(|value| !value.is_empty()));
     if let Some(effort) = effort {
         // Grok accepts `--effort` as alias for `--reasoning-effort`.
         argv.push("--effort".to_string());
         argv.push(effort.as_str().to_string());
     }
-    if let Some(prompt) = system_prompt {
-        argv.push("--rules".to_string());
-        argv.push(prompt.to_string());
-    }
+    append_opt_pair(&mut argv, "--rules", system_prompt);
     // Grok CLI has no `--mcp-config` flag — the claude inline-MCP block is
     // intentionally absent. Launch writes `<cwd>/.grok/config.toml`.
-    let _ = (adapter, auth_mode, mcp_config, managed_mcp_config);
     Ok(argv)
 }

package/crates/team-agent/src/provider/adapters/pi.rs

@@ -14,6 +14,7 @@ use std::path::Path;
 
 use crate::model::enums::ProviderEffort;
 use crate::provider::ProviderError;
+use crate::provider::command_helpers::{append_opt_pair, append_pair};
 
 #[derive(Debug, Clone, Copy)]
 pub(crate) enum PiSessionSelector<'a> {
@@ -60,38 +61,27 @@ pub(crate) fn build_pi_command_argv(
         "-e".to_string(),
         request.extension.to_string_lossy().into_owned(),
     ];
-    if let Some(model) = request.model {
-        argv.push("--model".to_string());
-        argv.push(model.to_string());
-    }
+    append_opt_pair(&mut argv, "--model", request.model);
     if let Some(effort) = request.effort {
         argv.push("--thinking".to_string());
         argv.push(effort.as_str().to_string());
     }
-    argv.extend([
-        "--append-system-prompt".to_string(),
-        request.system_prompt.to_string(),
-    ]);
+    append_pair(&mut argv, "--append-system-prompt", request.system_prompt);
     if let Some(session_dir) = request.session_dir {
-        argv.extend([
-            "--session-dir".to_string(),
-            session_dir.to_string_lossy().into_owned(),
-        ]);
+        append_pair(&mut argv, "--session-dir", session_dir.to_string_lossy().into_owned());
     }
     // The shared lifecycle materializer always revalidates resume root/path/header.
     // Keep the pure argv builder usable before a fixture root is materialized, while
     // refusing a missing exact file once the recorded path's parent exists.
     match request.session {
         PiSessionSelector::Fresh { session_id } if !session_id.trim().is_empty() => {
-            argv.push("--session-id".to_string());
-            argv.push(session_id.to_string());
+            append_pair(&mut argv, "--session-id", session_id);
         }
         PiSessionSelector::Resume { path }
             if !path.as_os_str().is_empty()
                 && (!path.parent().is_some_and(Path::is_dir) || path.is_file()) =>
         {
-            argv.push("--session".to_string());
-            argv.push(path.to_string_lossy().into_owned());
+            append_pair(&mut argv, "--session", path.to_string_lossy().into_owned());
         }
         PiSessionSelector::Resume { path } if !path.as_os_str().is_empty() => {
             return Err(ProviderError::ResumeUnavailable(format!(
@@ -105,7 +95,6 @@ pub(crate) fn build_pi_command_argv(
             ));
         }
     }
-    argv.push("--name".to_string());
-    argv.push(request.agent_id.to_string());
+    append_pair(&mut argv, "--name", request.agent_id);
     Ok(argv)
 }

package/crates/team-agent/src/provider/command_helpers.rs

@@ -0,0 +1,45 @@
+//! Pure append operations. Callers own ordering, filtering, escaping and env-unset policy.
+use std::collections::BTreeMap;
+
+pub(crate) fn append_pair(argv: &mut Vec<String>, flag: &str, value: impl Into<String>) {
+    argv.push(flag.to_string());
+    argv.push(value.into());
+}
+
+pub(crate) fn append_opt_pair(argv: &mut Vec<String>, flag: &str, value: Option<&str>) {
+    if let Some(value) = value {
+        append_pair(argv, flag, value);
+    }
+}
+
+pub(crate) fn append_env_pair(env: &mut BTreeMap<String, String>, key: &str, value: Option<&str>) {
+    if let Some(value) = value {
+        env.insert(key.to_string(), value.to_string());
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn append_preserves_order_and_raw_values() {
+        let mut argv = vec!["cli".to_string()];
+        append_opt_pair(&mut argv, "--absent", None);
+        append_opt_pair(&mut argv, "--empty", Some(""));
+        append_pair(&mut argv, "--raw", " \"'\\\n ".to_string());
+        append_pair(&mut argv, "--repeat", "first");
+        append_pair(&mut argv, "--repeat", "last");
+        assert_eq!(argv, ["cli", "--empty", "", "--raw", " \"'\\\n ", "--repeat", "first", "--repeat", "last"]);
+    }
+
+    #[test]
+    fn env_append_preserves_absence_empty_values_and_last_write() {
+        let mut env = BTreeMap::from([("Z".to_string(), "old".to_string())]);
+        append_env_pair(&mut env, "Z", None);
+        assert_eq!(env["Z"], "old");
+        append_env_pair(&mut env, "A", Some(""));
+        append_env_pair(&mut env, "Z", Some(" \"'\\\n "));
+        assert_eq!(env.into_iter().collect::<Vec<_>>(), vec![("A".to_string(), "".to_string()), ("Z".to_string(), " \"'\\\n ".to_string())]);
+    }
+}