@team-agent/installer 0.5.103 → 0.5.105

package/crates/team-agent/src/lifecycle/tests/cursor_require_explicit_model_red.rs

@@ -31,35 +31,23 @@ use team_agent::transport::test_support::OfflineTransport;
 
 #[test]
 #[serial(env)]
-fn cursor_role_missing_model_refuses_to_start() {
+fn cursor_role_missing_model_uses_provider_default() {
     let ws = tmp_dir("cursor-no-model");
     let team = write_role_team(&ws, "cursortm", "cursor_writer", None, None);
     let transport = OfflineTransport::new();
-    let result = quick_start_with_transport_in_workspace(
+    quick_start_with_transport_in_workspace(
         &ws,
         &team,
         None,
         true,
         Some("cursortm"),
         &transport,
-    );
-    let err = match result {
-        Ok(report) => panic!("cursor role without model must refuse; report={report:?}"),
-        Err(error) => error.to_string(),
-    };
-    let lower = err.to_ascii_lowercase();
-    assert!(
-        lower.contains("model"),
-        "error must name the missing field; err={err}"
-    );
-    assert!(
-        lower.contains("built-in") || lower.contains("builtin") || err.contains("内建"),
-        "error must name the built-in default; err={err}"
-    );
+    )
+    .expect("Cursor may use its provider-native model default");
+    let argv = first_spawn_argv(&transport);
     assert!(
-        transport.spawn_records().is_empty(),
-        "refusal must happen before spawn; records={:?}",
-        transport.spawn_records()
+        !argv.iter().any(|arg| arg == "--model"),
+        "an omitted model must not fabricate a --model argument: {argv:?}"
     );
 }
 

package/crates/team-agent/src/lifecycle/tests/grok_require_explicit_model_red.rs

@@ -27,11 +27,10 @@ use serial_test::serial;
 use team_agent::lifecycle::quick_start_with_transport_in_workspace;
 use team_agent::transport::test_support::OfflineTransport;
 
-/// 1. grok 角色缺 model ⇒ 启动被拒，错误含 "model" 与「内建默认 / 隐式来源」。
-///    40e91fba 上会成功启动（有 overlay / 有 spawn）⇒ 本条红。
+/// An omitted Grok role model preserves the provider-native default.
 #[test]
 #[serial(env)]
-fn grok_role_missing_model_refuses_to_start() {
+fn grok_role_missing_model_uses_provider_default() {
     let ws = tmp_dir("grok-no-model");
     let home = tmp_dir("grok-no-model-home");
     seed_grok_home(&home, Some(&ws));
@@ -46,51 +45,19 @@ fn grok_role_missing_model_refuses_to_start() {
     );
     let transport = OfflineTransport::new();
 
-    let result = quick_start_with_transport_in_workspace(
+    quick_start_with_transport_in_workspace(
         &ws,
         &team,
         None,
         true,
         Some("grokteam"),
         &transport,
-    );
-
-    let err = match result {
-        Ok(report) => panic!(
-            "grok role without model must refuse to start; a built-in default \
-             would silently pick the model; report={report:?}"
-        ),
-        Err(error) => error.to_string(),
-    };
-    let lower = err.to_ascii_lowercase();
-    assert!(
-        lower.contains("model"),
-        "error must name the missing field; err={err}"
-    );
-    assert!(
-        lower.contains("built-in") || lower.contains("builtin") || err.contains("内建"),
-        "error must name the built-in default the framework would fill; err={err}"
-    );
-    assert!(
-        lower.contains("implicit") || err.contains("隐式"),
-        "error must reject every implicit source, not just one fallback; err={err}"
-    );
-    assert!(
-        err.contains("model: grok-4.6") || err.contains("model: grok-4"),
-        "error must show how to write the field; err={err}"
-    );
-    assert!(
-        !err.to_ascii_lowercase().contains("worktree") && !err.contains("then retry"),
-        "must not promise a remedy this version cannot honor; err={err}"
-    );
-    assert!(
-        transport.spawn_records().is_empty(),
-        "refusal must happen before spawn; records={:?}",
-        transport.spawn_records()
-    );
+    )
+    .expect("Grok may use its provider-native model default");
+    let argv = first_spawn_argv(&transport);
     assert!(
-        !ws.join(".grok").join("config.toml").exists(),
-        "must refuse before writing grok overlay; leftover .grok/config.toml means the seat started"
+        !argv.iter().any(|arg| arg == "--model"),
+        "an omitted model must not fabricate a --model argument: {argv:?}"
     );
 }
 

package/crates/team-agent/src/lifecycle/tests/pi_compiler_red.rs

@@ -86,7 +86,8 @@ fn pi_role_ignores_tools_and_preserves_provider_defaults() {
 
     let defaults = valid_role_with("")
         .replace("model: team-agent/qwen3.8-27b\n", "")
-        .replace("effort: medium\n", "");
+        .replace("effort: medium\n", "")
+        .replace("dangerously_skip_permissions: true\n", "");
     let team_meta = Value::Map(vec![
         (
             "provider_models".to_string(),
@@ -105,16 +106,21 @@ fn pi_role_ignores_tools_and_preserves_provider_defaults() {
         ),
     ]);
     let compiled = compile_pi_role_with_team(&defaults, &team_meta)
-        .expect("Pi model and effort may use provider defaults");
+        .expect("omitted model and effort preserve provider-native defaults");
     assert_eq!(
         compiled.agent.get("model"),
-        Some(&Value::Str("openai-codex/gpt-6-luna".to_string())),
-        "omitted Pi model uses the Luna default rather than team metadata"
+        Some(&Value::Null),
+        "omitted Pi model stays unset rather than using team metadata"
     );
     assert_eq!(
         compiled.agent.get("effort"),
-        Some(&Value::Str("max".to_string())),
-        "omitted Pi effort uses the global max default rather than team metadata"
+        None,
+        "omitted Pi effort stays unset rather than using team metadata"
+    );
+    assert_eq!(
+        compiled.agent.get("dangerously_skip_permissions"),
+        Some(&Value::Bool(false)),
+        "omitted Pi bypass defaults to safe false"
     );
 
     let models = parse_pi_list_models_table(CATALOG).expect("catalog fixture");
@@ -162,10 +168,10 @@ fn pi_role_uses_standard_bypass_field_without_fabricating_argv() {
 
     let missing_ack = valid_role_with("").replace("dangerously_skip_permissions: true\n", "");
     let compiled = compile_pi_role(&missing_ack)
-        .expect("omitted bypass metadata defaults to true");
+        .expect("omitted bypass metadata defaults to false");
     assert_eq!(
         compiled.agent.get("dangerously_skip_permissions"),
-        Some(&Value::Bool(true))
+        Some(&Value::Bool(false))
     );
 }
 

package/crates/team-agent/src/lifecycle/tests/pi_dual_entry_red.rs

@@ -216,18 +216,22 @@ fn pi_leader_and_teammate_body(hermetic: &HermeticTestEnv) {
 
     std::fs::write(
         &role,
-        "---\nname: worker-a\nrole: developer\nprovider: pi\nauth_mode: subscription\ntools:\n  - mcp_team\ndangerously_skip_permissions: true\n---\nworker contract\n",
+        "---\nname: worker-a\nrole: developer\nprovider: pi\nauth_mode: subscription\ntools:\n  - mcp_team\n---\nworker contract\n",
     )
     .expect("write provider-default teammate role");
     let defaults = compile_role_agent(&role, &Value::Map(Vec::new()), "/workspace")
-        .expect("provider: pi teammate may use Pi model and effort defaults");
+        .expect("provider: pi teammate may preserve provider-native defaults");
     assert_eq!(
         defaults.agent.get("model"),
-        Some(&Value::Str("openai-codex/gpt-6-luna".to_string()))
+        Some(&Value::Null)
     );
     assert_eq!(
         defaults.agent.get("effort"),
-        Some(&Value::Str("max".to_string()))
+        None
+    );
+    assert_eq!(
+        defaults.agent.get("dangerously_skip_permissions"),
+        Some(&Value::Bool(false))
     );
     std::fs::remove_dir_all(root).expect("remove role fixture");
 

package/crates/team-agent/src/lifecycle/worker_command_context.rs

@@ -58,7 +58,7 @@ pub(crate) struct WorkerCommandAgent {
     system_prompt_file: Option<String>,
     output_contract_format: Option<String>,
     communication_mode: CommunicationMode,
-    /// Missing `dangerously_skip_permissions` defaults to true; an explicit false remains respected.
+    /// Missing `dangerously_skip_permissions` defaults to false; only explicit true enables bypass.
     dangerously_skip_permissions: bool,
 }
 
@@ -110,9 +110,9 @@ impl WorkerCommandAgent {
                     .get("communication_mode")
                     .and_then(crate::model::yaml::Value::as_str),
             )?,
-            dangerously_skip_permissions: !matches!(
+            dangerously_skip_permissions: matches!(
                 agent.get("dangerously_skip_permissions"),
-                Some(crate::model::yaml::Value::Bool(false))
+                Some(crate::model::yaml::Value::Bool(true))
             ),
         })
     }
@@ -167,7 +167,7 @@ impl WorkerCommandAgent {
             dangerously_skip_permissions: agent
                 .get("dangerously_skip_permissions")
                 .and_then(serde_json::Value::as_bool)
-                .unwrap_or(true),
+                .unwrap_or(false),
         })
     }
 }

package/crates/team-agent/src/model/enums.rs

@@ -213,15 +213,6 @@ pub enum Backend {
     Pty,
 }
 
-/// agent permission mode(schema `agent.permission_mode`;compiler 恒发 `restricted`)。
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum PermissionMode {
-    Restricted,
-    Ask,
-    Trusted,
-}
-
 /// tmux pane 存活态(`state.py:336-341`)。**`Unknown` 既不可当 dead 也不可当 live**
 /// (owner-gate `state.py:382` 用 `!= LIVE`)—— 穷尽 match,不 fallthrough(§11)。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]

package/crates/team-agent/src/model/spec.rs

@@ -1136,7 +1136,7 @@ mod tests {
     }
 
     // 0.5.66 bypass 单源 §4.1:7 个生命周期入口共享编译后的 spec。
-    // 缺失 role frontmatter 值时由编译器注入 true；此处锁定公共编译入口的默认结果。
+    // 缺失 role frontmatter 值时编译为安全默认 false；此处锁定公共编译入口的结果。
     #[test]
     fn test_all_7_triggers_use_compiled_default_bypass() {
         let team = std::env::temp_dir().join(format!(
@@ -1165,7 +1165,7 @@ mod tests {
             .expect("compiled spec has a worker");
         assert_eq!(
             agent.get("dangerously_skip_permissions"),
-            Some(&Yaml::Bool(true))
+            Some(&Yaml::Bool(false))
         );
         let _ = std::fs::remove_dir_all(&team);
     }

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

@@ -11,9 +11,9 @@
 //! maturity: wired
 //! ---
 //!
-//! Cursor `agent` CLI（与 `cursor-agent` 同二进制）。主路径与
-//! `.team/scripts/cursor_seat.sh` 实测一致：
-//!   `--trust --sandbox disabled --workspace <物理路径> [--force] [--model]`
+//! Cursor `agent` CLI（与 `cursor-agent` 同二进制）。默认不跳过信任或沙箱设置。
+//! 显式 bypass 时才使用 `.team/scripts/cursor_seat.sh` 的 trusted/unsandboxed 选项：
+//!   `--workspace <物理路径> [--trust --sandbox disabled --force] [--model]`
 //! Role 不入 argv，写 `<workspace>/.cursor/rules/*.mdc` + `alwaysApply: true`。
 //! MCP 无 `--mcp-config`；身份必须写进 `.cursor/mcp.json` 的 env 表
 //! （cursor 不把父进程 TEAM_AGENT_* 传给 MCP 子进程）。
@@ -57,14 +57,13 @@ pub(crate) fn cursor_agent_base_command(
     effort: Option<crate::model::enums::ProviderEffort>,
 ) -> Result<Vec<String>, ProviderError> {
     let mut argv = vec!["agent".to_string()];
-    // --trust 跳过 Workspace Trust 闸（已实测）。无此 flag 会停在 Do you trust。
-    argv.push("--trust".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());
         argv.push("--force".to_string());
     }
-    // 与 cursor_seat.sh 主路径一致。沙箱实际隔离面未再拆，但 flag 本身已实测。
-    argv.push("--sandbox".to_string());
-    argv.push("disabled".to_string());
     if let Some(model) = model {
         argv.push("--model".to_string());
         argv.push(model.to_string());

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

@@ -1,7 +1,7 @@
 //!
 //! purpose: Grok CLI argv + permission deny 映射；MCP 不走 CLI flag
 //! contract: launch 写 `<cwd>/.grok/config.toml`；未登录 / 目录未信任必须拒绝启动。
-//!   角色缺 model 必须拒绝启动（禁止内建 / team / CLI 任何隐式默认）。
+//!   未指定 model 时不注入 `--model`，由 Grok CLI 使用原生默认。
 //!   未知工具映射记成 Unsupported，不发明 deny 名
 //! mcp_injection: dir_scoped —— 每席必须独立工作目录；同 cwd 多席会静默串台，故拒绝。
 //!   对照 claude/codex 是 argv 作用域（`--mcp-config`），同目录多席没有这个问题。
@@ -71,23 +71,10 @@ pub(crate) fn grok_base_command(
     if dangerously_skip_permissions {
         argv.push("--always-approve".to_string());
     }
-    let model = match model.map(str::trim).filter(|value| !value.is_empty()) {
-        Some(model) => model,
-        None => {
-            return Err(ProviderError::Command(
-                "grok launch requires an explicit model. \
-Without an explicit model the framework fills a built-in default (grok-4 for grok), \
-so the seat silently gets a model and context window that are not in the role file, \
-while argv still looks normal. The role file must name the model itself; \
-built-in defaults, team-level defaults, and the Grok CLI global default are all implicit sources. \
-Set the role front-matter field, for example:\n\
-model: grok-4.6"
-                    .to_string(),
-            ));
-        }
-    };
-    argv.push("--model".to_string());
-    argv.push(model.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());
+    }
     if let Some(effort) = effort {
         // Grok accepts `--effort` as alias for `--reasoning-effort`.
         argv.push("--effort".to_string());

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

@@ -308,21 +308,14 @@ fn test_grok_build_command_bypass_flag_when_dangerous() {
 }
 
 #[test]
-fn test_grok_build_command_refuses_missing_model() {
+fn test_grok_build_command_omits_missing_model() {
     let adapter = get_adapter(Provider::Grok);
-    let err = adapter
+    let argv = adapter
         .build_command(AuthMode::Subscription, None, None, None)
-        .expect_err("grok must refuse to build argv without an explicit model");
-    let text = err.to_string();
-    assert!(
-        text.to_ascii_lowercase().contains("model"),
-        "error must name model; got {text}"
-    );
+        .expect("missing model preserves the provider-native default");
     assert!(
-        text.to_ascii_lowercase().contains("built-in")
-            || text.to_ascii_lowercase().contains("builtin")
-            || text.contains("内建"),
-        "error must name the built-in default the framework would fill; got {text}"
+        !argv.iter().any(|arg| arg == "--model"),
+        "missing model must not fabricate a --model argument: {argv:?}"
     );
     assert!(
         argv_contains_adjacent(
@@ -348,12 +341,8 @@ fn test_cursor_agent_build_command_includes_workspace_flag() {
         "cursor argv must carry `--workspace {{workspace}}`: {argv:?}"
     );
     assert!(
-        argv_contains_adjacent(&argv, &["--trust"]),
-        "cursor argv must carry documented --trust: {argv:?}"
-    );
-    assert!(
-        argv_contains_adjacent(&argv, &["--sandbox", "disabled"]),
-        "cursor argv must carry documented --sandbox disabled: {argv:?}"
+        !argv.iter().any(|arg| arg == "--trust" || arg == "--sandbox"),
+        "safe Cursor command must not opt into trust or disabled sandbox: {argv:?}"
     );
     assert!(
         !argv.iter().any(|a| a == "--rules" || a == "--append-system-prompt"),
@@ -509,8 +498,11 @@ fn test_cursor_fresh_plan_has_no_session_id_and_no_resume() {
         plan.argv
     );
     assert!(
-        argv_contains_adjacent(&plan.argv, &["--trust"]),
-        "fresh cursor must keep --trust; argv={:?}",
+        !plan
+            .argv
+            .iter()
+            .any(|arg| arg == "--trust" || arg == "--sandbox"),
+        "default Cursor plan must not opt into trust or disabled sandbox; argv={:?}",
         plan.argv
     );
 }
@@ -550,10 +542,10 @@ fn test_cursor_resume_plan_requires_chat_id_and_never_emits_empty_resume() {
 }
 
 #[test]
-fn pi_wire_roundtrip_requires_backing_and_has_no_builtin_model() {
+fn pi_wire_roundtrip_requires_backing() {
     use crate::provider::wire::{
-        aliases, builtin_provider_model, command_name, parse_canonical_provider, parse_provider,
-        provider_wire, requires_resume_backing,
+        aliases, command_name, parse_canonical_provider, parse_provider, provider_wire,
+        requires_resume_backing,
     };
 
     let provider = Provider::Pi;
@@ -563,7 +555,6 @@ fn pi_wire_roundtrip_requires_backing_and_has_no_builtin_model() {
     assert_eq!(aliases(provider), &["pi"]);
     assert_eq!(command_name(provider), "pi");
     assert!(requires_resume_backing(provider));
-    assert_eq!(builtin_provider_model(provider), None);
 }
 
 #[test]

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

@@ -88,31 +88,6 @@ pub(crate) fn requires_resume_backing(provider: Provider) -> bool {
     )
 }
 
-pub(crate) fn provider_model_keys(provider: Provider) -> &'static [&'static str] {
-    match provider {
-        Provider::Claude => &["claude", "claude_code"],
-        Provider::ClaudeCode => &["claude_code", "claude"],
-        Provider::Codex => &["codex"],
-        Provider::Copilot => &["copilot"],
-        Provider::GeminiCli => &["gemini_cli"],
-        Provider::Grok => &["grok"],
-        Provider::CursorAgent => &["cursor_agent"],
-        Provider::Pi => &["pi"],
-        Provider::Fake => &["fake"],
-    }
-}
-
-pub(crate) fn builtin_provider_model(provider: Provider) -> Option<&'static str> {
-    match provider {
-        Provider::Claude | Provider::ClaudeCode => Some("claude-sonnet-4-6"),
-        Provider::Codex => Some("gpt-5.5"),
-        // grok: compiler 另有缺 model 硬闸，这里的 builtin 不再被 grok 角色吃到。
-        // cursor_agent: 禁止隐式默认（本机 shim 会剥 sonnet-4-thinking）；缺 model 编译失败。
-        Provider::Grok => Some("grok-4"),
-        Provider::CursorAgent | Provider::Pi => None,
-        Provider::Copilot | Provider::GeminiCli | Provider::Fake => None,
-    }
-}
 
 /// All aliases (including the canonical wire form) that parse to `provider`.
 /// The canonical wire form is always the first entry, so callers that need
@@ -235,10 +210,8 @@ mod tests {
             "model spec must validate providers through typed helpers"
         );
         assert!(
-            compiler_rs.contains("parse_canonical_provider")
-                && compiler_rs.contains("provider_model_keys")
-                && compiler_rs.contains("wire_builtin_provider_model"),
-            "compiler effort/model defaults must use typed provider helpers"
+            compiler_rs.contains("parse_canonical_provider"),
+            "compiler must validate providers through typed helpers"
         );
         assert!(
             delivery_rs.contains("parse_canonical_provider")

package/crates/team-agent/src/state/repository.rs

@@ -162,7 +162,8 @@ impl<'a> StateRepository<'a> {
         test_support::before_commit();
         let team_key = match intent {
             StateWriteIntent::ResultCollection { owner_team_id } => owner_team_id,
-            StateWriteIntent::ForkAgent { team_key, .. } => Some(team_key),
+            StateWriteIntent::ForkAgent { team_key, .. }
+            | StateWriteIntent::StartAgent { team_key, .. } => Some(team_key),
             _ => {
                 return Err(StateError::SaveFailed(
                     "intent does not accept a bounded Team delta".into(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.103",
+  "version": "0.5.105",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -20,9 +20,9 @@
     "team-agent-installer": "npm/install.mjs"
   },
   "optionalDependencies": {
-    "@team-agent/cli-darwin-arm64": "0.5.103",
-    "@team-agent/cli-darwin-x64": "0.5.103",
-    "@team-agent/cli-linux-x64": "0.5.103"
+    "@team-agent/cli-darwin-arm64": "0.5.105",
+    "@team-agent/cli-darwin-x64": "0.5.105",
+    "@team-agent/cli-linux-x64": "0.5.105"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",

package/skills/team-agent/SKILL.md

@@ -1,39 +1,89 @@
 ---
 name: team-agent
-description: Use only when the user explicitly asks to start, operate, inspect, shutdown, or restart a Team Agent team. Treat the team-agent CLI as a sealed appliance.
+description: Use when the user asks to create, operate, inspect, or stop a Team Agent team. Treat the CLI as the public interface.
 requires_team_agent: ">=0.5.0"
-last_verified_against: "0.5.66"
 ---
 # Team Agent
-Sealed appliance for someone who just got the CLI. Operator handbook (permissions, models, routing, recovery): `references/team-agent-operator.md`.
-If `team-agent --version` differs from `last_verified_against`, learn from the live CLI before copying examples:
-```bash
-team-agent --version
-team-agent --help
-team-agent doctor --help
+
+The current assistant is the **leader**. Workers use separate role files and report through Team Agent. Start from a tmux-addressable terminal or supported agent pane, in the workspace root (the parent of the team directory).
+
+## Decide before creating a team
+
+**The user decides each worker's provider and permission bypass. Do not silently choose Pi, true, or false.** Reuse an explicit user policy when it covers the worker; otherwise explain the choices and ask before starting.
+
+Use existing resources rather than establishing new accounts: `team-agent doctor --workspace . --json` reports discovered tools, but installed does not mean authenticated and an absent entry or unknown auth is not proof of unavailability. For providers supported by `models`, use `team-agent models --provider NAME` to check exact model IDs. Do not inspect credentials, automatically log in, or silently substitute a provider after a failed probe.
+
+| Choice | What to explain |
+|---|---|
+| Pi | One Agent tool can use several model catalogs; explicit models require a qualified ID such as `openai-codex/gpt-6-luna` |
+| Codex | The user's existing Codex workflow, native tools, permissions and resumable sessions |
+| Claude / Claude Code | The user's existing Claude workflow, models, native tools and session behavior |
+| Bypass `true` | Fewer permission interruptions, but broader automatic execution authority |
+| Bypass `false` | Keep the selected tool's native permissions; human confirmation may interrupt unattended work |
+
+False is **not** a read-only or sandbox guarantee. Native permission capabilities differ between tools. Suggest combinations based on the user's installed tools, subscriptions and task: for example, an explicitly chosen Codex implementer and Claude reviewer, or two Pi workers when those are the available resources. Different workers may use different providers; an existing worker cannot change provider.
+
+## Create and start
+
+Keep the goal in `TEAM.md` and each worker's instructions in `agents/*.md`. The filename stem is the worker's in-team short name.
+
+```text
+.team/current/
+  TEAM.md
+  agents/reviewer.md
 ```
-**Launch** from a tmux-addressable pane: `team-agent claude` or `team-agent codex`, then `team-agent quick-start .team/current`. For a plain-text team directory, use `team-agent quick-start <plain-text-team-dir>`. Do not start a real team from a naked terminal; workers use independent background windows on the workspace-scoped tmux server.
-**Operate**
-- Dispatch: `team-agent send TO MESSAGE` (positional TO; `--watch-result` is deprecated). After success, do not poll with `sleep` / `status` / `inbox` / `collect`. TO has two co-equal logical forms: an in-team short name (`team-agent send reviewer "..."`) and a fully qualified `<workspace>::<team>/<agent>`. Use the qualified form across workspaces.
-- Inspect: `team-agent status` / `status --json`; `ok: true` plus `ready: false` is not a crash.
-- Lifecycle: `restart .` resumes a stopped team; `add-agent NAME --role-file FILE` adds or `--force` recreates one worker; `shutdown --workspace .` stops. Do not shutdown the team to add a worker.
-- Documents: `TEAM.md` and `agents/*.md` may be plain text/Markdown with no frontmatter; the whole team body is its objective and the whole role body is the prompt. Default worker id is the filename stem, provider `pi`, model `openai-codex/gpt-6-luna`, effort `max`, and bypass enabled. Valid optional frontmatter can override supported metadata.
-- On a structured failure `action`, run that action first, then stop. Do not guess flags. `coordinator.session_missing` is self-healing; re-check `status --json`, do not shutdown.
-The current user-facing agent is the leader (orchestrate only). Worker MCP exposes exactly `send_message`, `report_result`, and optional `get_team_status`; lifecycle management stays on the authorized native CLI. Workers call `report_result` exactly once. Nested teams: `references/team-in-team.md`.
-## Provider Capability Matrix
-See `references/team-agent-operator.md` for Claude / Codex / Copilot / Gemini / fake. `quick-start` / `restart` / `claim-leader` JSON is compact by default; pass `--detail` only for internal diagnostics.
-| Provider | Resume | Turn-state detection | Per-worker model override | Team Agent fork |
-|---|---|---|---|---|
-| `grok` | yes (`--resume <id>`, archive-gated) | no | yes (role `model` required) | yes (`--fork-session` + new `--session-id`) |
-| `cursor_agent` | yes (`--resume <chatId>`, archive-gated) | no | required on role; same-family catalog id may take effect; unknown id silent-fallback; pane chrome ≠ proof | **no — `CapabilityUnsupported`** |
-| `pi` | yes (exact `--session <backing-path>`, not selector/continue) | Unknown (no JSONL turn-state reader) | yes (role `model` / `effort`, catalog-validated) | yes (full snapshot into separate seat/session; exact backing resume) |
-Grok / `cursor_agent` have no JSONL turn-state reader (classify → Unknown). Pi `fork-agent SOURCE --as TARGET` requires a captured Pi subscription source and reports both session ids plus the target backing path; it does not mutate the source session.
-## Provider Prep
-### Cursor provider notes
-To opt into Cursor, use optional frontmatter with `provider: cursor_agent` (not `cursor`; launcher verb `team-agent cursor`) and `auth_mode: subscription`; no profile or bypass field is required. `agent_id` (legacy `name`) and `role` can be omitted, but Cursor still requires an explicit `model:`.
-The model flag stays on argv; same-family catalog ids can change pane chrome, while unknown ids silent-fallback without warning. Pick a catalog id; after spawn, `capture-pane` once for chrome. Pane chrome does not prove the live model.
-One `cursor_agent` per workspace; a second seat fail-closes because `.cursor/mcp.json` is directory-scoped and overwrites `TEAM_AGENT_ID`. Several Cursor seats need separate workspace directories. Same seat, fresh context: `reset-agent --discard-session`.
-`clone-agent` copies the source role but starts fresh. Runtime role replacement: `clone-agent` → `stop-agent` → `remove-agent --confirm` (deletes `.team/dynamic-role-files/`) → write role file → `add-agent --role-file` → dispatch.
-- Restart emits `--resume <chatId>` when `store.db` / `meta.json` exist; the gate does not read chat text. Persist anything that must survive restart.
-- Delivery sends one Enter; a second Enter interrupts the turn.
-- After spawn, the pane footer should show `Cursor Agent v<version>`. Do not use `strings` to probe the binary.
+
+For a **new plan**, record the user's two decisions in every role. This example assumes the user selected Pi and bypass false; it is not a default:
+
+```markdown
+---
+provider: pi
+dangerously_skip_permissions: false
+---
+Review the change and report concrete regression risks.
+```
+
+```sh
+team-agent quick-start .team/current
+team-agent send reviewer "Review this change"
+team-agent inbox reviewer -n 3
+```
+
+Traditional file-based quick-start/compile behavior remains supported, including legacy minimal role documents; no conversion to CLI-created roles is required. Legacy interpretation is not permission to silently choose settings for a new user plan. Model and effort may remain unset; preserve the existing file compiler's native/default interpretation rather than inventing a model or effort.
+
+To add a **new** seat to an existing team, provider and bypass must be explicitly defined in the CLI or role file. A complete traditional role file needs no repeated flags. If both sources define a field, equal values are accepted and **conflicting values are rejected before any write or startup**:
+
+```sh
+# These values must be the user's choices, not inferred defaults.
+team-agent add-agent analyst --provider pi --bypass true --prompt "Analyze the proposed change"
+# auditor.md already contains the user's provider and bypass decisions.
+team-agent add-agent auditor --role-file /absolute/path/to/auditor.md
+```
+
+Add creates and immediately starts the seat. Ordinary add rejects an occupied ID, including stopped seats. Disaster recovery has one explicit exception: `add-agent ID --role-file FILE --force` may reuse the existing force-recreate lifecycle only when the registered old pane is positively confirmed dead and no live target cohort exists. A live seat or unknown/missing death proof is refused; force is not a routine configuration-update shortcut. External role files are imported into the team's `agents/ID.md` and left untouched. A file already at that path is used in place, without copying itself.
+
+## Change and start an existing worker
+
+**Stop first if it is running.** Start never implicitly kills or restarts a running worker:
+
+```sh
+team-agent stop-agent reviewer
+team-agent start-agent reviewer --effort high --bypass true
+team-agent stop-agent reviewer
+team-agent start-agent reviewer --prompt "Review only regression risks; do not change product code"
+```
+
+Start updates the same role file and recompiles it before normal startup. Omitted options preserve the file's values and body; `--prompt` replaces the permanent role body, not a one-time task message. `--bypass true` and `--bypass false` are explicit values, not bare switches. Model, effort and an existing profile can also be set. Direct file edits followed by start use the same reload path.
+
+A different `--provider`, including a manually edited role provider, is rejected before launch. A matching provider is allowed. Create a separate ID to use a different engine. If startup fails, the role file and runtime spec are restored to their pre-command contents; the command reports failure, not an applied update.
+
+Profiles keep provider authentication, endpoints and custom-model settings local. Imported roles use this team's/workspace's `profiles`, never the original external directory. Prepare a named profile locally through the public profile commands; do not search for or copy external credentials. Never put secrets in `TEAM.md` or a role file. See [the operator reference](references/team-agent-operator.md) for existing profile and field details. Supported metadata also includes `agent_id` (legacy `name`), `role`, `auth_mode`, and `communication_mode`; old `tools`, `permission_mode`, and `label` keys do not configure a worker.
+
+## Inspect and stop
+
+Use `team-agent status --json` for readiness and the installed command's `--help` for syntax. `ok: true` with `ready: false` means the team is not ready; follow the reported action. Accepted/queued send is not the worker's reply: wait for a natural response or result. Use `<workspace>::<team>/<agent>` when a fully qualified recipient is needed.
+
+Worker MCP provides `send_message`, `report_result`, and `get_team_status`. Lifecycle actions remain on the authorized CLI. See [nested teams](references/team-in-team.md) only when needed. Stop the selected team with `team-agent shutdown --workspace .` when authorized.
+
+---
+This skill is a concise public guide. Do not infer a tested version from package metadata; verify the installed CLI with `team-agent --version` when version-specific behavior matters.