@team-agent/installer 0.5.109 → 0.5.111

package/crates/team-agent/src/cli/models.rs

@@ -298,7 +298,8 @@ mod tests {
     #[cfg(unix)]
     #[test]
     fn search_survives_unrelated_spaced_model_ids() {
-        let catalog = include_str!("../lifecycle/tests/fixtures/pi_list_models_spaced_ids.stdout.txt");
+        let catalog =
+            include_str!("../lifecycle/tests/fixtures/pi_list_models_spaced_ids.stdout.txt");
         let path = fixture(&format!("printf '%s' '{catalog}'"));
         let result = cmd_models_with(
             &ModelsArgs {
@@ -370,7 +371,8 @@ mod tests {
             &["models", "--provider", "cursor_agent", "--json"],
         );
         let text = public_cli_text(&output);
-        let calls = std::fs::read_to_string(agent.program.with_extension("count")).unwrap_or_default();
+        let calls =
+            std::fs::read_to_string(agent.program.with_extension("count")).unwrap_or_default();
         drop(agent);
         assert!(output.status.success(), "{text}");
         assert_eq!(calls, "1:--list-models\n");
@@ -405,12 +407,19 @@ mod tests {
         let no_match = run_public_models_cli(
             &grok.program,
             grok.response.as_deref(),
-            &["models", "--provider", "grok", "--search", "definitely-absent"],
+            &[
+                "models",
+                "--provider",
+                "grok",
+                "--search",
+                "definitely-absent",
+            ],
         );
         let json_text = public_cli_text(&json);
         let human_text = public_cli_text(&human);
         let no_match_text = public_cli_text(&no_match);
-        let calls = std::fs::read_to_string(grok.program.with_extension("count")).unwrap_or_default();
+        let calls =
+            std::fs::read_to_string(grok.program.with_extension("count")).unwrap_or_default();
         drop(grok);
         assert!(json.status.success(), "{json_text}");
         assert!(human.status.success(), "{human_text}");
@@ -422,10 +431,15 @@ mod tests {
         assert_eq!(value["auth_basis"], "catalog_visibility");
         let models = value["models"].as_array().unwrap();
         assert_eq!(
-            models.iter().map(|model| model["model_id"].as_str().unwrap()).collect::<Vec<_>>(),
+            models
+                .iter()
+                .map(|model| model["model_id"].as_str().unwrap())
+                .collect::<Vec<_>>(),
             vec!["grok-4.7", "grok-4.7-build-fast", "grok-4.5", "grok-4.6"]
         );
-        assert!(models.iter().all(|model| model["provider"] == "grok" && model["vendor"] == "xai" && model["aliases"] == json!([])));
+        assert!(models.iter().all(|model| model["provider"] == "grok"
+            && model["vendor"] == "xai"
+            && model["aliases"] == json!([])));
         assert_eq!(models[0]["default"], false);
         assert_eq!(models[3]["default"], true);
         assert!(human_text.contains("grok-4.7-build-fast"));
@@ -471,7 +485,8 @@ mod tests {
                 &["models", "--provider", "grok", "--json"],
             );
             let text = public_cli_text(&output);
-            let calls = std::fs::read_to_string(grok.program.with_extension("count")).unwrap_or_default();
+            let calls =
+                std::fs::read_to_string(grok.program.with_extension("count")).unwrap_or_default();
             outcomes.push((name, output.status.success(), text, calls));
         }
         for (name, success, text, calls) in outcomes {
@@ -481,21 +496,32 @@ mod tests {
             assert_eq!(value["schema_version"], "models.v1", "{name}");
             assert_eq!(value["ok"], false, "{name}");
             assert_eq!(value["models"], json!([]), "{name}");
-            assert!(!value["error"].as_str().unwrap().to_ascii_lowercase().contains("unsupported model provider"), "{name}: {text}");
+            assert!(
+                !value["error"]
+                    .as_str()
+                    .unwrap()
+                    .to_ascii_lowercase()
+                    .contains("unsupported model provider"),
+                "{name}: {text}"
+            );
         }
     }
 
     #[cfg(unix)]
     #[test]
     fn grok_nonzero_native_command_is_not_a_successful_empty_catalog() {
-        let grok = CliFixture::new(fixture_program("grok", "printf 'private diagnostic' >&2\nexit 7"));
+        let grok = CliFixture::new(fixture_program(
+            "grok",
+            "printf 'private diagnostic' >&2\nexit 7",
+        ));
         let output = run_public_models_cli(
             &grok.program,
             None,
             &["models", "--provider", "grok", "--json"],
         );
         let text = public_cli_text(&output);
-        let calls = std::fs::read_to_string(grok.program.with_extension("count")).unwrap_or_default();
+        let calls =
+            std::fs::read_to_string(grok.program.with_extension("count")).unwrap_or_default();
         drop(grok);
         assert!(!output.status.success(), "{text}");
         assert_eq!(calls, "1:models\n");
@@ -503,7 +529,14 @@ mod tests {
         let value: Value = serde_json::from_str(text.trim()).unwrap();
         assert_eq!(value["ok"], false);
         assert_eq!(value["models"], json!([]));
-        assert!(value["error"].as_str().unwrap().to_ascii_lowercase().contains("grok"), "{text}");
+        assert!(
+            value["error"]
+                .as_str()
+                .unwrap()
+                .to_ascii_lowercase()
+                .contains("grok"),
+            "{text}"
+        );
     }
 
     #[cfg(unix)]
@@ -518,10 +551,20 @@ mod tests {
         let text = public_cli_text(&output);
         let value: Value = serde_json::from_str(text.trim()).unwrap();
         assert_eq!(value["ok"], false);
-        assert!(value["error"].as_str().unwrap().to_ascii_lowercase().contains("grok"), "{text}");
+        assert!(
+            value["error"]
+                .as_str()
+                .unwrap()
+                .to_ascii_lowercase()
+                .contains("grok"),
+            "{text}"
+        );
         assert!(value["action"].as_str().unwrap().contains("grok"), "{text}");
         assert!(crate::cli::emit::default_help().contains("grok"));
-        assert!(crate::cli::spec::command_spec("models").unwrap().usage.contains("grok"));
+        assert!(crate::cli::spec::command_spec("models")
+            .unwrap()
+            .usage
+            .contains("grok"));
 
         let unsupported = run_public_models_cli(
             &missing.program,
@@ -533,7 +576,13 @@ mod tests {
         drop(missing);
         assert!(!output.status.success());
         assert!(!unsupported.status.success());
-        assert!(unsupported_value["action"].as_str().unwrap().contains("grok"), "{unsupported_text}");
+        assert!(
+            unsupported_value["action"]
+                .as_str()
+                .unwrap()
+                .contains("grok"),
+            "{unsupported_text}"
+        );
     }
 
     #[cfg(unix)]
@@ -579,7 +628,10 @@ mod tests {
     #[cfg(unix)]
     impl CliFixture {
         fn new(program: std::path::PathBuf) -> Self {
-            Self { program, response: None }
+            Self {
+                program,
+                response: None,
+            }
         }
     }
 
@@ -614,7 +666,10 @@ mod tests {
                 "--nocapture",
             ])
             .env("TEAM_AGENT_MODELS_CHILD", "1")
-            .env("TEAM_AGENT_MODELS_ARGS", serde_json::to_string(args).unwrap())
+            .env(
+                "TEAM_AGENT_MODELS_ARGS",
+                serde_json::to_string(args).unwrap(),
+            )
             .env("PATH", path.parent().unwrap())
             .env_remove("PI_PROVIDER")
             .env_remove("PI_MODEL")
@@ -719,7 +774,10 @@ mod tests {
     fn with_native_mode<T>(
         mode: &str,
         action: impl FnOnce() -> T,
-    ) -> (T, crate::lifecycle::launch::pi_mcp::PiCatalogTestObservation) {
+    ) -> (
+        T,
+        crate::lifecycle::launch::pi_mcp::PiCatalogTestObservation,
+    ) {
         let receipt = native_timeout_receipt();
         assert!(!receipt.exists());
         let result = crate::lifecycle::launch::pi_mcp::with_pi_catalog_test_observation(
@@ -1122,9 +1180,8 @@ mod tests {
     fn runner_fails_closed_for_nonzero_oversize_timeout_and_unavailable() {
         let fail = native_timeout_fixture();
         let started = Instant::now();
-        let (failed_result, fail_observation) = with_native_mode("exit7", || {
-            run_catalog(&fail, Duration::from_secs(1), 1024)
-        });
+        let (failed_result, fail_observation) =
+            with_native_mode("exit7", || run_catalog(&fail, Duration::from_secs(1), 1024));
         let elapsed = started.elapsed();
         assert_eq!(
             failed_result.unwrap_err(),
@@ -1161,9 +1218,8 @@ mod tests {
         assert_eq!(failed.exit, ExitCode::Error);
         assert!(!text.contains("sensitive-token"));
         let big = native_timeout_fixture();
-        let (big_result, big_observation) = with_native_mode("oversize", || {
-            run_catalog(&big, Duration::from_secs(1), 8)
-        });
+        let (big_result, big_observation) =
+            with_native_mode("oversize", || run_catalog(&big, Duration::from_secs(1), 8));
         assert!(big_result.unwrap_err().contains("bounded output"));
         assert_eq!(big_observation.spawn_count, 1);
         assert_eq!(big_observation.argv, vec!["--list-models"]);
@@ -1217,7 +1273,7 @@ mod tests {
         );
         assert_eq!(
             crate::cli::spec::command_spec("models").unwrap().usage,
-            "usage: team-agent models [--provider pi|cursor_agent|codex|claude|claude_code|grok] [QUERY|--search TEXT] [--json]"
+            "team-agent models [--provider pi|cursor_agent|codex|claude|claude_code|grok] [QUERY|--search TEXT] [--json]"
         );
     }
 

package/crates/team-agent/src/cli/named_address.rs

@@ -71,6 +71,25 @@ pub(crate) struct NamedAddressError {
     /// `requested_name`/`suggested_name` without re-parsing. Absent
     /// for exact refusals like empty-workspace.
     pub requested_name: Option<String>,
+    // Presentation only: never serialized or used as routing authority.
+    human_scope: Option<PathBuf>,
+    human_team: Option<String>,
+}
+
+pub(crate) fn human_address_reason(reason: &str) -> Option<&'static str> {
+    Some(match reason {
+        "name_invalid" => "收信队友名不正确；请使用队友列表中的名称。",
+        "workspace_not_found" => "所选项目目录不存在；请核对项目路径。",
+        "state_not_found" | "workspace_no_state" => {
+            "所选项目还没有可用队伍；首次起队用 quick-start，已有队伍恢复用 restart。"
+        }
+        "team_key_not_found" => "所选项目没有这支队伍；请核对 --workspace 和 --team。",
+        "leader_not_attached" => "主控还没有连接到这支队伍；请先体检，按提示恢复连接。",
+        "name_not_resolvable" => "当前队伍没有这个队友；请先查看队友列表。",
+        "name_not_live" => "该队友当前未运行或连接已失效；请查看状态再恢复。",
+        "name_ambiguous" => "有多个同名对象；请明确选择项目和队伍，不猜对象。",
+        _ => return None,
+    })
 }
 
 impl NamedAddressError {
@@ -86,7 +105,77 @@ impl NamedAddressError {
             available_team_keys: Vec::new(),
             suggested_name: None,
             requested_name: None,
+            human_scope: None,
+            human_team: None,
+        }
+    }
+
+    fn with_human_scope(mut self, workspace: Option<&Path>, team: Option<&str>) -> Self {
+        self.human_scope = workspace.map(Path::to_path_buf);
+        if self.human_team.is_none() {
+            self.human_team = team.map(str::to_string);
         }
+        self
+    }
+
+    pub(crate) fn human_guidance(&self, requested: &str) -> (String, String) {
+        let workspace = self.human_scope.as_deref();
+        let mut message = format!(
+            "{}\n你刚才填写的是 {requested:?}。",
+            human_address_reason(self.kind.as_str()).unwrap_or("未能找到可用的收信队友。")
+        );
+        if let Some(workspace) = workspace {
+            message.push_str(&format!("\n所选项目：{:?}。", workspace.to_string_lossy()));
+        }
+        if let Some(team) = self.human_team.as_deref() {
+            message.push_str(&format!("\n所选队伍：{team:?}。"));
+        }
+        let mut action = "没有可靠的拼写建议；请先核对项目和队伍，不猜对象。".to_string();
+        for candidate in &self.candidates {
+            if let (Some(agent), Some(team)) = (
+                candidate.get("agent_id").and_then(Value::as_str),
+                candidate.get("team_key").and_then(Value::as_str),
+            ) {
+                message.push_str(&format!(
+                    "\n候选队伍 {team:?}，队友 {agent:?}；请确认是否是你要找的对象。"
+                ));
+            }
+        }
+        if let Some(candidate) = self.suggested_name.as_deref().and_then(|suggested| {
+            self.candidates
+                .iter()
+                .find(|candidate| candidate.get("name").and_then(Value::as_str) == Some(suggested))
+        }) {
+            if let (Some(workspace), Some(agent), Some(team)) = (
+                workspace,
+                candidate.get("agent_id").and_then(Value::as_str),
+                candidate.get("team_key").and_then(Value::as_str),
+            ) {
+                if !agent.is_empty()
+                    && !team.is_empty()
+                    && !agent
+                        .chars()
+                        .chain(team.chars())
+                        .chain(workspace.to_string_lossy().chars())
+                        .any(char::is_control)
+                {
+                    if let Some(command) =
+                        super::adapters::send_command(agent, workspace, Some(team))
+                    {
+                        action = format!("你是否想发给 {agent:?}、队伍 {team:?}？确认后将任务内容替换到这个例子；本次没有发送：\n{command}");
+                    }
+                }
+            }
+        }
+        if let Some(workspace) =
+            workspace.filter(|path| !path.to_string_lossy().chars().any(char::is_control))
+        {
+            action.push_str(&format!(
+                "\n也可查看可用队友列表：\nteam-agent status --workspace {}",
+                super::adapters::shell_quote(&workspace.to_string_lossy())
+            ));
+        }
+        (message, action)
     }
 
     pub(crate) fn n38_message(&self) -> String {
@@ -188,9 +277,7 @@ impl NamedAddressError {
                 })
             })
             .collect();
-        let best = ranked
-            .first()
-            .map(|agent_id| format!("{team}/{agent_id}"));
+        let best = ranked.first().map(|agent_id| format!("{team}/{agent_id}"));
         self.with_scoped_suggestions(requested_display, candidate_values, best)
     }
 
@@ -216,9 +303,7 @@ impl NamedAddressError {
         // returned candidate (RED-4). Falls back to a status-JSON
         // hint when no candidate cleared the threshold.
         if let Some(best) = best_copyable {
-            self.action = format!(
-                "Did you mean `{best}`? Rerun with `--to-name {best}`."
-            );
+            self.action = format!("Did you mean `{best}`? Rerun with `--to-name {best}`.");
         } else {
             self.action = format!(
                 "No close matches for `{requested}`. \
@@ -430,8 +515,14 @@ pub(crate) fn resolve_name_for_cli(
     // registry-to-E6 internal helper deliberately pass `None` so
     // caller-supplied `--team` never overrides a full address.
     let parsed = normalize_bare_with_team_scope(parsed, bare_team_scope);
-    let target_workspace = resolve_workspace(sender_workspace, parsed.workspace.as_deref())?;
-    let state = load_state_checked(&target_workspace)?;
+    let requested_team = match &parsed.target {
+        ParsedTarget::TeamEntity { team, .. } => Some(team.as_str()),
+        _ => None,
+    };
+    let target_workspace = resolve_workspace(sender_workspace, parsed.workspace.as_deref())
+        .map_err(|error| error.with_human_scope(None, requested_team))?;
+    let state = load_state_checked(&target_workspace)
+        .map_err(|error| error.with_human_scope(Some(&target_workspace), requested_team))?;
     let transport = transport_for_cli_target(&target_workspace, &state, &parsed);
     let resolved = resolve_in_workspace(
         sender_workspace,
@@ -439,7 +530,8 @@ pub(crate) fn resolve_name_for_cli(
         &state,
         &parsed,
         transport.as_ref(),
-    )?;
+    )
+    .map_err(|error| error.with_human_scope(Some(&target_workspace), requested_team))?;
     Ok((resolved, transport))
 }
 
@@ -487,8 +579,8 @@ pub(crate) fn parse_leader_target_workspace_and_team(
     match parsed.target {
         ParsedTarget::TeamEntity { team, entity } if entity == "leader" => {
             let state = load_state_checked(&target_workspace)?;
-            let canonical = canonical_named_team_key(&target_workspace, &state, &team)
-                .unwrap_or(team);
+            let canonical =
+                canonical_named_team_key(&target_workspace, &state, &team).unwrap_or(team);
             Ok(Some((target_workspace, canonical)))
         }
         _ => Ok(None),
@@ -594,7 +686,7 @@ fn resolve_in_workspace(
         ParsedTarget::TeamEntity { team, entity } => {
             let canonical = canonical_named_team_key(target_workspace, state, team)
                 .unwrap_or_else(|| team.clone());
-            if entity == "leader" {
+            let result = if entity == "leader" {
                 resolve_leader(
                     sender_workspace,
                     target_workspace,
@@ -613,7 +705,11 @@ fn resolve_in_workspace(
                     parsed,
                     transport,
                 )
-            }
+            };
+            result.map_err(|mut error| {
+                error.human_team = Some(canonical);
+                error
+            })
         }
         ParsedTarget::SessionWindow { session, window } => resolve_session_window(
             sender_workspace,
@@ -976,11 +1072,7 @@ fn resolve_leader(
     let socket = string_field(receiver, "tmux_socket")
         .map(str::to_string)
         .or_else(|| transport.tmux_endpoint());
-    match crate::messaging::resolve_live_leader_channel(
-        target_workspace,
-        receiver,
-        transport,
-    ) {
+    match crate::messaging::resolve_live_leader_channel(target_workspace, receiver, transport) {
         crate::messaging::LeaderChannelResolution::Live(
             crate::messaging::LiveLeaderChannel::DirectTmux(channel),
         ) => Ok(ResolvedNamedAddress {
@@ -1194,8 +1286,8 @@ fn transport_for_cli_target(
     parsed: &ParsedNamedAddress,
 ) -> Box<dyn Transport> {
     if let ParsedTarget::TeamEntity { team, entity } = &parsed.target {
-        let canonical = canonical_named_team_key(target_workspace, state, team)
-            .unwrap_or_else(|| team.clone());
+        let canonical =
+            canonical_named_team_key(target_workspace, state, team).unwrap_or_else(|| team.clone());
         if entity == "leader" {
             let team_scoped_socket = team_entry(state, &canonical)
                 .and_then(|entry| entry.get("leader_receiver"))
@@ -1302,11 +1394,8 @@ fn canonical_named_team_key(
     if team_entry(state, requested).is_some() || is_legacy_single_team_active(state, requested) {
         return Some(requested.to_string());
     }
-    let selected = crate::state::projection::select_runtime_state(
-        target_workspace,
-        Some(requested),
-    )
-    .ok()?;
+    let selected =
+        crate::state::projection::select_runtime_state(target_workspace, Some(requested)).ok()?;
     let canonical = selected
         .get("active_team_key")
         .and_then(Value::as_str)

package/crates/team-agent/src/cli/route.rs

@@ -0,0 +1,212 @@
+//! Host-global route management: raw argv, no workspace selection or error log.
+
+use super::{CmdOutput, CmdResult, ExitCode};
+use crate::provider::argv_route::{self, Config, Mutation, Override, RouteError};
+use crate::provider::Provider;
+use serde_json::{json, Value};
+
+pub(crate) const HELP: &str = "做什么：\n设置工具启动时额外使用的命令行参数，默认关闭。\n用法：team-agent route [status|enable|disable|show [TOOL]|set TOOL -- ARG...|add TOOL -- ARG...|clear TOOL] [--json]\n\n怎么用：\nstatus 看开关；enable 开启；disable 关闭；show 看全部或指定工具的参数。\nset 替换参数；add 追加参数；clear 清除指定工具的参数；--json 给程序读取。\nTOOL 是已支持的工具名称，如 pi/codex/claude/copilot/grok/cursor_agent。\n第一个 -- 后全是工具的字面参数，包含 --help/--json 也不会被这里解析。\n配置保存在 ~/.team-agent/argv-routing.json；影响全机，不按项目或队伍隔离。\nTEAM_AGENT_CLI_ARGV_ROUTING 环境变量优先于保存的开关。\nExamples（可复制）：\nteam-agent route status\nteam-agent route set pi -- --mode text\nteam-agent route enable\n\n下一步（Next Action）：\n用 route show pi 核对参数；仅影响下一次启动，不改变正在运行的对话。\n没有开启或没有配置时，工具仍按原参数启动；不了解参数用途时保持关闭。";
+
+struct Request {
+    operation: String,
+    provider: Option<Provider>,
+    tokens: Vec<String>,
+    json: bool,
+}
+
+fn usage() -> RouteError {
+    RouteError {
+        error: "参数不完整或不正确；set/add 需要工具名、-- 和至少一个工具参数".to_string(),
+        reason: "argv_route_usage",
+        action: "请按 team-agent route --help 的 Examples 填写；例如 team-agent route set pi -- --mode text".to_string(),
+        config_path: None,
+    }
+}
+
+fn parse(args: &[String], delimiter: usize) -> Result<Request, RouteError> {
+    let mut json = false;
+    let mut positionals = Vec::new();
+    for token in &args[..delimiter] {
+        if token == "--json" {
+            if json {
+                return Err(usage());
+            }
+            json = true;
+        } else if token.starts_with('-') {
+            return Err(usage());
+        } else {
+            positionals.push(token.as_str());
+        }
+    }
+    let operation = positionals.first().copied().unwrap_or("status");
+    let provider_required = matches!(operation, "set" | "add" | "clear");
+    let provider_allowed = provider_required || operation == "show";
+    if !matches!(
+        operation,
+        "status" | "enable" | "disable" | "show" | "set" | "add" | "clear"
+    ) || positionals.len() > if provider_allowed { 2 } else { 1 }
+        || (provider_required && positionals.len() != 2)
+    {
+        return Err(usage());
+    }
+    let provider = positionals
+        .get(1)
+        .map(|raw| argv_route::parse_route_provider(raw).ok_or_else(usage))
+        .transpose()?;
+    let tokens = if matches!(operation, "set" | "add") {
+        if delimiter == args.len() || delimiter + 1 == args.len() {
+            return Err(usage());
+        }
+        let tokens = args[delimiter + 1..].to_vec();
+        if !argv_route::valid_tokens(&tokens) {
+            return Err(usage());
+        }
+        tokens
+    } else {
+        if delimiter != args.len() {
+            return Err(usage());
+        }
+        Vec::new()
+    };
+    Ok(Request {
+        operation: operation.to_string(),
+        provider,
+        tokens,
+        json,
+    })
+}
+
+fn switch_fields(
+    path: Option<&std::path::Path>,
+    persisted: Option<bool>,
+    present: bool,
+    override_state: Override,
+) -> Value {
+    json!({
+        "config_path": path,
+        "persisted_enabled": persisted,
+        "effective_enabled": override_state.effective(persisted.unwrap_or(false)),
+        "enabled_source": override_state.source(present),
+        "override_status": override_state.status(),
+    })
+}
+
+fn execute(request: &Request) -> Result<Value, RouteError> {
+    let path = argv_route::config_path()?;
+    let (config, present) = match request.operation.as_str() {
+        "enable" => argv_route::mutate(&path, Mutation::Enable(true))?,
+        "disable" => argv_route::mutate(&path, Mutation::Enable(false))?,
+        "set" | "add" | "clear" => {
+            let provider = request.provider.ok_or_else(usage)?;
+            let mutation = match request.operation.as_str() {
+                "set" => Mutation::Set(provider, request.tokens.clone()),
+                "add" => Mutation::Add(provider, request.tokens.clone()),
+                _ => Mutation::Clear(provider),
+            };
+            argv_route::mutate(&path, mutation)?
+        }
+        _ => argv_route::read_config(&path)?,
+    };
+    let override_state = Override::current();
+    let mut value = switch_fields(Some(&path), Some(config.enabled), present, override_state);
+    value["ok"] = json!(true);
+    value["operation"] = json!(request.operation);
+    if let Some(provider) = request.provider {
+        add_provider_fields(&mut value, &config, provider);
+    } else if request.operation == "show" {
+        value["providers"] = json!(config.providers);
+    }
+    if override_state != Override::Unset {
+        value["notice"] = json!(format!(
+            "当前开关由环境变量 {} 决定（{}）",
+            argv_route::ENV_NAME,
+            override_state.status()
+        ));
+    }
+    Ok(value)
+}
+
+fn add_provider_fields(value: &mut Value, config: &Config, provider: Provider) {
+    if let Some(key) = argv_route::route_key(provider) {
+        value["provider"] = json!(key);
+        value["configured"] = json!(config.providers.contains_key(key));
+        value["argv"] = json!(config.providers.get(key).cloned().unwrap_or_default());
+    }
+}
+
+/// Route-only error renderer: reuse redaction/formatting, never cwd log policy.
+fn emit_error(error: RouteError, args: &[String], delimiter: usize, as_json: bool) -> ExitCode {
+    let is_usage = error.reason == "argv_route_usage";
+    let mut value = json!({
+        "ok": false, "error": error.error, "reason": error.reason,
+        "action": error.action, "config_path": error.config_path,
+    });
+    if !is_usage {
+        // Best-effort switch observation even when strict management read fails.
+        // No config content or invalid argv is included in the error channel.
+        let path = error.config_path.as_deref();
+        let loose = path
+            .and_then(|path| std::fs::read(path).ok())
+            .and_then(|bytes| serde_json::from_slice::<Value>(&bytes).ok());
+        let persisted = loose
+            .as_ref()
+            .and_then(|v| v.get("enabled"))
+            .and_then(Value::as_bool);
+        let fields = switch_fields(
+            path,
+            persisted,
+            path.is_some_and(std::path::Path::exists),
+            Override::current(),
+        );
+        if let (Some(target), Some(fields)) = (value.as_object_mut(), fields.as_object()) {
+            target.extend(fields.clone());
+        }
+        value["operation"] = json!(args[..delimiter]
+            .iter()
+            .find(|arg| !arg.starts_with('-'))
+            .map(String::as_str)
+            .unwrap_or("status"));
+    }
+    if is_usage {
+        value["next_actions"] = json!(["team-agent route --help"]);
+    }
+    if let Some(text) = super::emit(&CmdOutput::Json(value), as_json) {
+        if as_json {
+            println!("{text}");
+        } else {
+            eprintln!("{text}");
+        }
+    }
+    if is_usage {
+        if !as_json {
+            eprintln!("\n{HELP}");
+        }
+        ExitCode::Usage
+    } else {
+        ExitCode::Error
+    }
+}
+
+pub(crate) fn run(args: &[String]) -> ExitCode {
+    let delimiter = args
+        .iter()
+        .position(|arg| arg == "--")
+        .unwrap_or(args.len());
+    // Help and output-format controls stop at the first delimiter. Neither
+    // generic help scanning nor the old --no-display compatibility filter runs.
+    if args[..delimiter]
+        .iter()
+        .any(|arg| matches!(arg.as_str(), "--help" | "-h"))
+    {
+        println!("{HELP}");
+        return ExitCode::Ok;
+    }
+    let as_json = args[..delimiter].iter().any(|arg| arg == "--json");
+    match parse(args, delimiter) {
+        Ok(request) => match execute(&request) {
+            Ok(value) => super::emit::emit_result(CmdResult::from_json(value, request.json)),
+            Err(error) => emit_error(error, args, delimiter, as_json),
+        },
+        Err(error) => emit_error(error, args, delimiter, as_json),
+    }
+}