@team-agent/installer 0.4.8 → 0.4.10

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

@@ -4,7 +4,7 @@ use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 use std::process::Command;
 
-use crate::model::enums::{AuthMode, DisplayBackend, PaneLiveness, Provider};
+use crate::model::enums::{AuthMode, DisplayBackend, PaneLiveness, Provider, ProviderEffort};
 use crate::model::ids::AgentId;
 use crate::model::permissions::{self, AgentPermissionInput};
 use crate::model::yaml::{self, Value};
@@ -243,6 +243,16 @@ fn spawn_agents(
                 Some(&mcp_config),
             )?;
         let command_model = profile_launch.command_overrides.model.as_deref().or(model);
+        // 0.4.x provider effort MVP step 4 + 7: resolve effort and emit
+        // unsupported warning event when the spec asked for an effort the
+        // provider can't satisfy.
+        let agent_effort = provider_effort_for_spawn(agent, provider);
+        if let Some(event_value) =
+            provider_effort_event_if_dropped(agent, provider, agent_id_raw)
+        {
+            let _ = crate::event_log::EventLog::new(workspace)
+                .write("provider.effort_unsupported", event_value);
+        }
         let mut plan = adapter
             .build_command_plan(crate::provider::ProviderCommandContext {
                 auth_mode,
@@ -256,6 +266,7 @@ fn spawn_agents(
                 // adapters can pass `--name <agent_id>`. Codex has no
                 // equivalent flag and ignores the hint.
                 agent_id_hint: Some(agent_id_raw),
+                effort: agent_effort,
             })
             .map_err(|e| LifecycleError::Provider(e.to_string()))?;
         if !plan.managed_mcp_config && !profile_launch.managed_mcp_config {
@@ -320,7 +331,10 @@ fn spawn_agents(
         apply_mcp_auto_approval_env(&mut env, &safety);
         // Python providers.py:145 + launch/core.py:253 — fresh launch runs the worker
         // with cwd=workspace, same as the RS fork/add and restart paths.
-        let env_unset: Vec<String> = profile_launch.env_unset.iter().cloned().collect();
+        let env_unset: Vec<String> = extend_worker_env_unset_for_effort(
+            profile_launch.env_unset.iter().cloned().collect(),
+            provider,
+        );
         // BUG / C-1-2 / C-6-1 cr verdict — Copilot system_prompt 走 spawn env overlay +
         // per-worker AGENTS.md(B2 灵魂件降级):写
         //   <workspace>/.team/runtime/copilot-instructions/<agent_id>/AGENTS.md
@@ -1721,6 +1735,13 @@ fn running_agent_state(
         model.map_or(serde_json::Value::Null, |m| serde_json::json!(m)),
     );
     state.insert("auth_mode".to_string(), serde_json::json!(auth_mode));
+    // 0.4.x provider effort MVP step 8: persist resolved effort so restart
+    // / resume reads the same value (no re-resolution from role/team).
+    if let Some(effort_str) = agent.get("effort").and_then(Value::as_str) {
+        if !effort_str.is_empty() {
+            state.insert("effort".to_string(), serde_json::json!(effort_str));
+        }
+    }
     state.insert("profile".to_string(), profile);
     if agent.get("profile").is_some() {
         if let Some(profile_dir) = profile_dir {
@@ -2466,6 +2487,112 @@ fn parse_auth_mode(raw: &str) -> Option<AuthMode> {
     }
 }
 
+/// 0.4.x provider effort MVP step 4: low-level from a raw string. Returns
+/// `Some(effort)` when the level parses AND the provider supports it.
+pub(crate) fn provider_effort_from_raw(
+    raw: Option<&str>,
+    provider: Provider,
+) -> Option<ProviderEffort> {
+    let raw = raw?.trim();
+    if raw.is_empty() {
+        return None;
+    }
+    let effort = ProviderEffort::parse(raw)?;
+    if effort.is_supported_by(provider) {
+        Some(effort)
+    } else {
+        None
+    }
+}
+
+/// 0.4.x provider effort MVP step 7: warning event payload when the spec
+/// requested an effort level the provider does not support.
+pub(crate) fn provider_effort_event_payload(
+    raw: Option<&str>,
+    provider: Provider,
+    agent_id: &str,
+) -> Option<serde_json::Value> {
+    let raw = raw?.trim();
+    if raw.is_empty() {
+        return None;
+    }
+    let effort = ProviderEffort::parse(raw)?;
+    if effort.is_supported_by(provider) {
+        return None;
+    }
+    Some(serde_json::json!({
+        "agent_id": agent_id,
+        "provider": format!("{provider:?}").to_lowercase(),
+        "effort": effort.as_str(),
+        "action": "ignored",
+        "reason": "provider does not support effort",
+    }))
+}
+
+/// 0.4.x provider effort MVP step 9: defensive guarantee that `CLAUDE_EFFORT`
+/// is unset in the Claude/ClaudeCode worker spawn env. As of the
+/// `profile_launch::provider_env_unsets` update, the base list already
+/// includes `CLAUDE_EFFORT` for Claude — so this function is idempotent
+/// (returns input unchanged). Kept as a belt-and-braces guard so a future
+/// refactor that bypasses provider_env_unsets cannot silently drop the
+/// scrub. The structural win is in `tmux_backend::shell_command` which now
+/// filters env exports by env_unset (preventing inherited values from
+/// re-introducing keys we just unset).
+pub(crate) fn extend_worker_env_unset_for_effort(
+    base: Vec<String>,
+    provider: Provider,
+) -> Vec<String> {
+    if !matches!(provider, Provider::Claude | Provider::ClaudeCode) {
+        return base;
+    }
+    let mut out = base;
+    if !out.iter().any(|k| k == "CLAUDE_EFFORT") {
+        out.push("CLAUDE_EFFORT".to_string());
+    }
+    out
+}
+
+/// Convenience: resolve effort for a yaml::Value agent (spec / compiled).
+pub(crate) fn provider_effort_for_spawn(
+    agent: &crate::model::yaml::Value,
+    provider: Provider,
+) -> Option<ProviderEffort> {
+    provider_effort_from_raw(agent.get("effort").and_then(|v| v.as_str()), provider)
+}
+
+pub(crate) fn provider_effort_event_if_dropped(
+    agent: &crate::model::yaml::Value,
+    provider: Provider,
+    agent_id: &str,
+) -> Option<serde_json::Value> {
+    provider_effort_event_payload(
+        agent.get("effort").and_then(|v| v.as_str()),
+        provider,
+        agent_id,
+    )
+}
+
+/// Same as [`provider_effort_for_spawn`] but for serde_json state values
+/// (used by restart paths reading from `state.agents[id]`).
+pub(crate) fn provider_effort_for_spawn_json(
+    agent: &serde_json::Value,
+    provider: Provider,
+) -> Option<ProviderEffort> {
+    provider_effort_from_raw(agent.get("effort").and_then(serde_json::Value::as_str), provider)
+}
+
+pub(crate) fn provider_effort_event_if_dropped_json(
+    agent: &serde_json::Value,
+    provider: Provider,
+    agent_id: &str,
+) -> Option<serde_json::Value> {
+    provider_effort_event_payload(
+        agent.get("effort").and_then(serde_json::Value::as_str),
+        provider,
+        agent_id,
+    )
+}
+
 fn quick_start_requested_team_key<'a>(
     team_id: Option<&'a str>,
     name: Option<&'a str>,
@@ -3786,6 +3913,16 @@ fn upsert_agent_state_from_role(
             }
         }
     }
+    // 0.4.x provider effort MVP step 8 (dynamic add-agent): persist effort
+    // from the role doc front matter (compiler.rs validates syntax/semantics
+    // at compile; add-agent path validates here too in case of direct YAML).
+    if let Some(effort_str) = meta.get("effort").and_then(Value::as_str) {
+        if !effort_str.is_empty() {
+            if let Some(obj) = entry.as_object_mut() {
+                obj.insert("effort".to_string(), serde_json::json!(effort_str));
+            }
+        }
+    }
     if let Some(obj) = entry.as_object_mut() {
         persist_effective_approval_policy(obj, safety);
     }
@@ -4075,6 +4212,15 @@ pub fn fork_agent_with_transport(
             Some(&mcp_config),
         )?;
     let command_model = profile_launch.command_overrides.model.as_deref().or(model);
+    // 0.4.x provider effort MVP: fork inherits effort from the new agent JSON
+    // (compiler.rs propagated the role/team effort into the agent at fork-spawn).
+    let fork_effort = provider_effort_for_spawn(new_agent, provider);
+    if let Some(event_value) =
+        provider_effort_event_if_dropped(new_agent, provider, as_agent_id.as_str())
+    {
+        let _ = crate::event_log::EventLog::new(&workspace)
+            .write("provider.effort_unsupported", event_value);
+    }
     let mut plan = adapter
         .fork_plan(
             Some(&session_id),
@@ -4086,6 +4232,7 @@ pub fn fork_agent_with_transport(
                 tools: &resolved_tool_refs,
                 profile_launch: Some(&profile_launch),
                 agent_id_hint: Some(as_agent_id.as_str()),
+                effort: fork_effort,
             },
         )
         .map_err(|e| {
@@ -4111,7 +4258,10 @@ pub fn fork_agent_with_transport(
     // _tmux_session_exists — an ABSENT session => new-session (spawn_first), present => new-window
     // (spawn_into). The Rust restart seam (restart.rs spawn_agent_window) uses the same branch.
     let session_live = transport.has_session(&session_name).unwrap_or(false);
-    let env_unset: Vec<String> = profile_launch.env_unset.iter().cloned().collect();
+    let env_unset: Vec<String> = extend_worker_env_unset_for_effort(
+        profile_launch.env_unset.iter().cloned().collect(),
+        provider,
+    );
     let spawn_result = if session_live {
         transport.spawn_into_with_env_unset(
             &session_name,
@@ -4495,6 +4645,8 @@ fn upsert_forked_agent_state(
         "profile",
         "_profile_dir",
         "role",
+        // 0.4.x provider effort MVP step 8: fork inherits compiled effort.
+        "effort",
     ] {
         if let Some(value) = spec_agent.get(key) {
             entry.insert(key.to_string(), yaml_value_to_json(value));

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

@@ -415,7 +415,14 @@ fn provider_env_exports(
     exports
 }
 
-fn provider_env_unsets(provider: Provider, auth_mode: AuthMode) -> BTreeSet<String> {
+/// 0.4.x (CR C-1): exposed as `pub(crate)` so the leader launcher
+/// (leader/start.rs) can reuse the SAME Claude/Codex/Copilot env-unset set
+/// used by worker spawn. Single source of truth — adding a new provider env
+/// var to clean up means changing this one function. Audit grep guard in
+/// `crates/team-agent/src/leader/start.rs::leader_env_unset_for_provider`
+/// confirms the leader path imports from here and does not maintain its own
+/// duplicate list.
+pub(crate) fn provider_env_unsets(provider: Provider, auth_mode: AuthMode) -> BTreeSet<String> {
     let mut unsets = BTreeSet::new();
     match provider {
         Provider::Claude | Provider::ClaudeCode => {
@@ -443,6 +450,18 @@ fn provider_env_unsets(provider: Provider, auth_mode: AuthMode) -> BTreeSet<Stri
             unsets.insert("CLAUDE_CODE_ENTRYPOINT".to_string());
             unsets.insert("CLAUDE_CODE_EXECPATH".to_string());
             unsets.insert("CLAUDECODE".to_string());
+            // 0.4.x provider effort MVP step 9: CLAUDE_EFFORT carried from the
+            // launching shell would silently override the framework's effort
+            // decision (or, when no spec effort is configured, override the
+            // documented "provider default"). Scrubbing here is the single
+            // source — `extend_worker_env_unset_for_effort` is a thin alias
+            // that calls into this list. Applies to BOTH worker spawn AND
+            // leader spawn (leader_env_unset_for_provider also reads this).
+            // MVP scope: leader-effort is not configured yet, but if a
+            // launching shell already carries CLAUDE_EFFORT, the leader
+            // inheriting it would conflict with future leader-effort
+            // semantics. Scrub uniformly for predictability.
+            unsets.insert("CLAUDE_EFFORT".to_string());
             if auth_mode == AuthMode::CompatibleApi {
                 unsets.insert("ANTHROPIC_API_KEY".to_string());
             }

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

@@ -1058,6 +1058,15 @@ fn write_start_agent_start_event(
         .model
         .as_deref()
         .or(model);
+    // 0.4.x provider effort MVP: start_agent path preserves effort from the
+    // persisted agent JSON.
+    let start_agent_effort = crate::lifecycle::launch::provider_effort_for_spawn_json(&agent, provider);
+    if let Some(event_value) = crate::lifecycle::launch::provider_effort_event_if_dropped_json(
+        &agent, provider, agent_id.as_str(),
+    ) {
+        let _ = crate::event_log::EventLog::new(workspace)
+            .write("provider.effort_unsupported", event_value);
+    }
     let context = crate::provider::ProviderCommandContext {
         auth_mode,
         mcp_config: Some(&mcp_config),
@@ -1066,6 +1075,7 @@ fn write_start_agent_start_event(
         tools: &resolved_tool_refs,
         profile_launch: Some(&profile_launch),
         agent_id_hint: Some(agent_id.as_str()),
+        effort: start_agent_effort,
     };
     let mut plan = match session_id {
         Some(session_id) => adapter

package/crates/team-agent/src/lifecycle/restart/common.rs

@@ -114,6 +114,15 @@ pub(super) fn spawn_agent_window(
             Some(&mcp_config),
         )?;
     let command_model = profile_launch.command_overrides.model.as_deref().or(model);
+    // 0.4.x provider effort MVP: restart/resume preserves effort from the
+    // persisted agent JSON (state's agent["effort"] field, set by launch).
+    let restart_effort = crate::lifecycle::launch::provider_effort_for_spawn_json(agent, provider);
+    if let Some(event_value) = crate::lifecycle::launch::provider_effort_event_if_dropped_json(
+        agent, provider, agent_id.as_str(),
+    ) {
+        let _ = crate::event_log::EventLog::new(workspace)
+            .write("provider.effort_unsupported", event_value);
+    }
     let context = crate::provider::ProviderCommandContext {
         auth_mode,
         mcp_config: Some(&mcp_config),
@@ -122,6 +131,7 @@ pub(super) fn spawn_agent_window(
         tools: &resolved_tool_refs,
         profile_launch: Some(&profile_launch),
         agent_id_hint: Some(agent_id.as_str()),
+        effort: restart_effort,
     };
     let mut plan = match resume_session_id {
         Some(session_id) => adapter
@@ -167,7 +177,13 @@ pub(super) fn spawn_agent_window(
     // a per-agent YAML `spawn_cwd` field if one is set. Until then, override
     // > workspace; state-based override is silently dropped.
     let spawn_cwd = spawn_cwd_override.unwrap_or(workspace);
-    let env_unset: Vec<String> = profile_launch.env_unset.iter().cloned().collect();
+    // 0.4.x provider effort MVP step 9: scrub CLAUDE_EFFORT for Claude
+    // worker spawn so a parent shell env cannot silently override the
+    // framework's effort decision.
+    let env_unset: Vec<String> = crate::lifecycle::launch::extend_worker_env_unset_for_effort(
+        profile_launch.env_unset.iter().cloned().collect(),
+        provider,
+    );
 
     // 0.4.6 Stage 2: write actual spawn plan event BEFORE invoking the
     // transport spawn. Mirrors `launch.rs:359-380` (the reference impl)

package/crates/team-agent/src/messaging/mod.rs

@@ -102,7 +102,8 @@ pub use types::{
     CheckKind, CheckStatus, ContractSuiteCheck, DeliveryOutcome, DeliveryRefusal, DeliveryStage,
     DeliveryStatus, IdleEvaluation, LeaderNotificationKey, LeaderReceiver, PaneWidthQuery,
     ProviderSdkCalls, ReceiverMode, ScheduledKind, SelftestCheck, SelftestReport, SendEventPayload,
-    TrustRetryPayload, WatcherNotice, RESULT_DELIVERY_MAX_ATTEMPTS, SEND_RETRY_MAX_ATTEMPTS,
+    TrustRetryPayload, WatcherNotice, WorkerRuntimeState,
+    RESULT_DELIVERY_MAX_ATTEMPTS, SEND_RETRY_MAX_ATTEMPTS,
     TRUST_RETRY_BACKOFF_SECONDS, TRUST_RETRY_MAX_ATTEMPTS,
 };
 pub use watchers::{

package/crates/team-agent/src/messaging/types.rs

@@ -126,6 +126,92 @@ impl ActivityStatus {
     }
 }
 
+/// 0.4.x Phase 1 worker runtime-state (fg-pgrp + 5-state plan, CR APPROVED).
+///
+/// Canonical runtime-state enum surfaced by `team-agent status` and consumed
+/// by automatic-dispatch / idle-gate predicates. Distinct from
+/// [`ActivityStatus`] (which remains the internal classifier output for
+/// backwards compatibility) and from lifecycle `agents.<id>.status` (which
+/// remains launch/stop-owned: `running`/`paused`/`stopped`/etc.).
+///
+/// Rules:
+///   * `Busy` when `foreground_pgrp != agent_root_pgrp` (a child process
+///     occupies the terminal — provider is not at idle prompt).
+///   * `Unknown` is NEVER idle-eligible and must be treated as busy by
+///     automatic-dispatch / idle-gate predicates.
+///   * `ProbablyIdle` is a weak conclusion, not proof of idleness.
+///   * `Dead` when the pane is missing or the root process is gone.
+///   * `Blocked` when the worker is awaiting human confirmation (trust
+///     prompt, startup approval).
+///
+/// CR R4: deserialise with `#[serde(other)]` so a future variant added by
+/// a newer build does not crash an older reader (rolling upgrade safe).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum WorkerRuntimeState {
+    Dead,
+    Busy,
+    Blocked,
+    ProbablyIdle,
+    /// Default fallback. CR R4: also catches unknown wire strings via
+    /// `#[serde(other)]`.
+    #[serde(other)]
+    Unknown,
+}
+
+impl WorkerRuntimeState {
+    /// Wire string used by status/diagnose JSON.
+    pub fn as_wire(self) -> &'static str {
+        match self {
+            Self::Dead => "DEAD",
+            Self::Busy => "BUSY",
+            Self::Blocked => "BLOCKED",
+            Self::ProbablyIdle => "PROBABLY_IDLE",
+            Self::Unknown => "UNKNOWN",
+        }
+    }
+
+    /// Parse from wire string. Returns `Self::Unknown` for unknown literals
+    /// (defence-in-depth alongside `#[serde(other)]`).
+    pub fn parse_wire(value: &str) -> Self {
+        match value.trim() {
+            "DEAD" => Self::Dead,
+            "BUSY" => Self::Busy,
+            "BLOCKED" => Self::Blocked,
+            "PROBABLY_IDLE" => Self::ProbablyIdle,
+            _ => Self::Unknown,
+        }
+    }
+
+    /// True for states that MUST NOT receive automatic dispatch:
+    /// `Dead | Busy | Blocked | Unknown`. Only `ProbablyIdle` is safe.
+    /// CR R3 + Phase 1 §8 dispatch boundary.
+    pub fn blocks_automatic_dispatch(self) -> bool {
+        !matches!(self, Self::ProbablyIdle)
+    }
+
+    /// True only for `ProbablyIdle` — the sole idle candidate. `Unknown` is
+    /// NEVER idle (Iron Law: bug-071/077/085).
+    pub fn is_idle_candidate(self) -> bool {
+        matches!(self, Self::ProbablyIdle)
+    }
+
+    /// Map from the legacy [`ActivityStatus`] for backward-compat. Used by
+    /// status/diagnose code paths that have an old AgentActivity in hand
+    /// and need a runtime-state surface for the product enum.
+    ///   Working   → Busy
+    ///   Idle      → ProbablyIdle
+    ///   Stuck     → Unknown (CR rule: stale signals are never idle)
+    ///   Uncertain → Unknown
+    pub fn from_activity(activity: ActivityStatus) -> Self {
+        match activity {
+            ActivityStatus::Working => Self::Busy,
+            ActivityStatus::Idle => Self::ProbablyIdle,
+            ActivityStatus::Stuck | ActivityStatus::Uncertain => Self::Unknown,
+        }
+    }
+}
+
 /// 告警类型 (card §49;`scheduler.py:38` `_ALERT_TYPES`)。`stuck_cancel` 还接 `all` (展开全集)。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]

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

@@ -23,6 +23,71 @@ pub enum Provider {
     Fake,
 }
 
+/// 0.4.x Provider effort MVP: reasoning effort level passed to the provider.
+/// Configuration sources (resolution order):
+///   1. role doc front matter `effort: low|medium|high|xhigh|max`
+///   2. TEAM.md front matter `provider_effort: low|medium|high|xhigh|max`
+///   3. provider default (framework passes no flag)
+///
+/// Provider support:
+///   - claude / claude_code: low|medium|high|xhigh|max → `--effort <level>`
+///   - codex: low|medium|high|xhigh (NOT max) → `-c model_reasoning_effort=<level>`
+///   - copilot / gemini_cli / fake: unsupported — warning event, no flag
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum ProviderEffort {
+    #[serde(rename = "low")]
+    Low,
+    #[serde(rename = "medium")]
+    Medium,
+    #[serde(rename = "high")]
+    High,
+    #[serde(rename = "xhigh")]
+    XHigh,
+    #[serde(rename = "max")]
+    Max,
+}
+
+impl ProviderEffort {
+    /// Parse from a wire string. Returns None on unknown literal.
+    pub fn parse(value: &str) -> Option<Self> {
+        match value.trim() {
+            "low" => Some(Self::Low),
+            "medium" => Some(Self::Medium),
+            "high" => Some(Self::High),
+            "xhigh" => Some(Self::XHigh),
+            "max" => Some(Self::Max),
+            _ => None,
+        }
+    }
+
+    /// Wire string used by both CLI argv and state serialization.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Low => "low",
+            Self::Medium => "medium",
+            Self::High => "high",
+            Self::XHigh => "xhigh",
+            Self::Max => "max",
+        }
+    }
+
+    /// Effort levels Claude-only (Codex / others must reject `max`).
+    pub fn is_claude_only(self) -> bool {
+        matches!(self, Self::Max)
+    }
+
+    /// True when the given provider supports this effort level. `max` is
+    /// Claude-only; other levels are supported by Claude and Codex, ignored
+    /// by Copilot/Gemini/Fake (warning emitted at runtime).
+    pub fn is_supported_by(self, provider: Provider) -> bool {
+        match provider {
+            Provider::Claude | Provider::ClaudeCode => true,
+            Provider::Codex => !self.is_claude_only(),
+            Provider::Copilot | Provider::GeminiCli | Provider::Fake => false,
+        }
+    }
+}
+
 /// auth 模式(`AUTH_MODES` `profiles/constants.py:6`)。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]

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

@@ -250,8 +250,19 @@ fn basic_schema_errors(spec: &Yaml) -> Vec<String> {
     if !matches!(spec.get("version"), Some(Yaml::Int(1))) {
         e.push("/version: must equal 1".to_string());
     }
-    let team_keys = &["name", "mode", "objective", "workspace"];
-    check_keys_y(spec.get("team"), "/team", team_keys, team_keys, &mut e);
+    // 0.4.x provider effort MVP step 3: provider_effort is allowed but not required.
+    let team_required = &["name", "mode", "objective", "workspace"];
+    let team_allowed = &["name", "mode", "objective", "workspace", "provider_effort"];
+    check_keys_y(spec.get("team"), "/team", team_required, team_allowed, &mut e);
+    if let Some(team) = spec.get("team") {
+        if let Some(raw) = team.get("provider_effort").and_then(Yaml::as_str) {
+            if crate::model::enums::ProviderEffort::parse(raw).is_none() {
+                e.push(format!(
+                    "/team/provider_effort: unknown effort '{raw}' (allowed: low|medium|high|xhigh|max)"
+                ));
+            }
+        }
+    }
     let mode = spec.get("team").and_then(|t| t.get("mode")).and_then(Yaml::as_str);
     if !matches!(mode, Some("supervisor_worker" | "swarm_limited")) {
         e.push("/team/mode: invalid mode".to_string());
@@ -298,11 +309,32 @@ fn check_agent(agent: &Yaml, path: &str, errors: &mut Vec<String>) {
         "id", "role", "provider", "model", "working_directory", "system_prompt", "tools",
         "permission_mode", "preferred_for", "avoid_for", "output_contract", "paused", "auth_mode",
         "profile", "credential_ref", "forked_from",
+        // 0.4.x provider effort MVP step 3: per-agent effort override (resolved at compile).
+        "effort",
     ];
     check_keys_y(Some(agent), path, req, allowed, errors);
     if !agent.is_map() {
         return;
     }
+    // 0.4.x provider effort MVP step 3: effort syntactic + semantic validation.
+    if let Some(raw) = agent.get("effort").and_then(Yaml::as_str) {
+        match crate::model::enums::ProviderEffort::parse(raw) {
+            None => {
+                errors.push(format!(
+                    "{path}/effort: unknown effort '{raw}' (allowed: low|medium|high|xhigh|max)"
+                ));
+            }
+            Some(effort) if effort.is_claude_only() => {
+                let provider = agent.get("provider").and_then(Yaml::as_str).unwrap_or("");
+                if !matches!(provider, "claude" | "claude_code") {
+                    errors.push(format!(
+                        "{path}/effort: effort '{raw}' is only supported by claude/claude_code (provider: {provider})"
+                    ));
+                }
+            }
+            Some(_) => {}
+        }
+    }
     check_keys_y(agent.get("system_prompt"), &format!("{path}/system_prompt"), &["inline", "file"], &["inline", "file"], errors);
     check_list_y(agent.get("tools"), &format!("{path}/tools"), errors);
     check_list_y(agent.get("preferred_for"), &format!("{path}/preferred_for"), errors);

package/crates/team-agent/src/os_probe.rs

@@ -128,3 +128,82 @@ fn read_and_remove(path: &std::path::Path) -> Vec<u8> {
     let _ = std::fs::remove_file(path);
     stdout
 }
+
+/// 0.4.x Phase 1 (fg-pgrp): terminal foreground process-group probe.
+///
+/// macOS probe confirmed (2026-06-29, .team/artifacts/fg-pgrp-probe.md):
+/// `TIOCGPGRP` ioctl returns Errno 25 on tmux slave PTYs opened from a
+/// non-controlling process. We use `ps -o tpgid,pgid -p <pid>` instead —
+/// reliable on macOS AND Linux, no platform-specific cfg needed.
+///
+/// Returns `Ok(Some((tpgid, pgid)))` on success, `Ok(None)` when the PID
+/// is gone / ps returned no row / values unparseable. The caller maps
+/// `None` to `WorkerRuntimeState::Unknown` (never to idle — Iron Law).
+///
+/// `tpgid` = terminal foreground process group ID.
+/// `pgid`  = the agent root's own process group ID.
+/// `tpgid != pgid` means a child process owns the foreground (BUSY signal).
+///
+/// Bounded via [`run_bounded_command`] so a wedged ps cannot stall the
+/// coordinator tick.
+pub(crate) fn pane_foreground_and_root_pgrp(pane_pid: u32) -> io::Result<Option<(u32, u32)>> {
+    let mut command = Command::new("ps");
+    command.args(["-o", "tpgid=,pgid=", "-p", &pane_pid.to_string()]);
+    let output = bounded_command_output_with_probe(
+        &mut command,
+        "pane_foreground_and_root_pgrp",
+        Some(pane_pid),
+    )?;
+    if probe_timed_out() {
+        return Ok(None);
+    }
+    if !output.status.success() {
+        return Ok(None);
+    }
+    let text = String::from_utf8_lossy(&output.stdout);
+    let first_line = text.lines().next().unwrap_or("").trim();
+    if first_line.is_empty() {
+        return Ok(None);
+    }
+    let parts: Vec<&str> = first_line.split_whitespace().collect();
+    if parts.len() < 2 {
+        return Ok(None);
+    }
+    let tpgid = parts[0].parse::<i64>().ok();
+    let pgid = parts[1].parse::<i64>().ok();
+    match (tpgid, pgid) {
+        // ps prints `-1` for tpgid when there is no controlling terminal —
+        // treat as unknown rather than fabricating a u32.
+        (Some(t), Some(p)) if t > 0 && p > 0 => Ok(Some((t as u32, p as u32))),
+        _ => Ok(None),
+    }
+}
+
+#[cfg(test)]
+mod fg_pgrp_tests {
+    use super::*;
+
+    #[test]
+    fn pane_foreground_and_root_pgrp_self_returns_some_or_none() {
+        // The current test process is not necessarily attached to a
+        // controlling terminal (CI runs detached), so we accept Some OR
+        // None. The contract is: never panic, return io::Result.
+        let pid = std::process::id();
+        match pane_foreground_and_root_pgrp(pid) {
+            Ok(Some((tpgid, pgid))) => {
+                assert!(tpgid > 0 && pgid > 0, "positive pgid/tpgid");
+            }
+            Ok(None) => {} // headless / no tty — acceptable
+            Err(e) => panic!("probe must not error in normal env: {e}"),
+        }
+    }
+
+    #[test]
+    fn pane_foreground_and_root_pgrp_missing_pid_returns_none() {
+        // PID 1 is init/launchd — exists but we read fields; non-existent
+        // PIDs return Ok(None) (ps exits non-zero).
+        let result =
+            pane_foreground_and_root_pgrp(0xFFFF_FFFE).expect("must not error on missing pid");
+        assert!(result.is_none(), "missing pid → None");
+    }
+}