fix(install): honor frontmatter provider with flag > frontmatter > default precedence (fixes #414) (#431)

`cao install <profile.md>` silently ignored the profile's frontmatter
`provider:` key: the Click --provider option defaulted to kiro_cli and
install_service.install_agent branched on that argument alone, so a
profile declaring `provider: codex` installed as a kiro_cli agent with
exit 0 and no warning. Install was the only entry point ignoring
frontmatter — launch/assign/handoff already resolve it via
resolve_provider().

The install provider now resolves with the same precedence as the
launch paths: explicit --provider flag > frontmatter `provider:` >
DEFAULT_PROVIDER.

- CLI: --provider defaults to None; help text documents the precedence;
  the summary line echoes the provider the service actually resolved.
- install_service.install_agent: accepts provider=None; explicit bad
  providers still fail fast BEFORE any URL download or env mutation;
  a bogus frontmatter provider logs a warning (same wording as
  resolve_provider) and falls back to the default. InstallResult gains
  a `provider` field carrying the resolved winner.
- API: InstallAgentProfileRequest.provider defaults to None.
- ops-MCP install_profile: provider defaults to None and is omitted
  from the request body when not explicit, so all three entry points
  behave identically. Built-in store profiles carry no frontmatter
  provider and keep today's default-provider behavior.

Test matrix: flag wins over frontmatter; frontmatter wins when the flag
is absent; both absent -> DEFAULT_PROVIDER; invalid frontmatter provider
warns and falls back; explicit invalid --provider fails before download;
built-in (no frontmatter) keeps the default; API and ops-MCP forward
None for frontmatter resolution.

Co-authored-by: haofeif <56006724+haofeif@users.noreply.github.com>

Author: call-me-ram

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- honor profile frontmatter `provider:` during install (flag > frontmatter > default) (#414)
 ### Security
 
 - clear the `py/clear-text-storage-sensitive-data` CodeQL false positive (code-scanning alert #142) by renaming the local `secret` fixture variable in two `memory_service` secret-gate tests to `gated_content`. CodeQL's name-based heuristic classified the variable named `secret` as a sensitive-data source and traced it into the memory-wiki write (an intentionally plaintext, by-design markdown sink). The literal is the canonical AWS documentation example key, not a real credential; the value and all assertions are unchanged, so the federated secret-gate rejection and global-scope allow paths are still exercised exactly. No production behavior change

src/cli_agent_orchestrator/api/main.py

@@ -397,10 +397,14 @@ class InstallAgentProfileRequest(BaseModel):
 
     ``env_vars`` travels in the JSON body rather than as a query parameter so
     that any secrets callers inject are not written to HTTP access logs.
+
+    ``provider`` may be omitted (None): the install service then honours the
+    profile's frontmatter ``provider:`` key, falling back to the default
+    provider — the same flag > frontmatter > default precedence as the CLI.
     """
 
     source: str
-    provider: str = DEFAULT_PROVIDER
+    provider: Optional[str] = None
     env_vars: Optional[Dict[str, str]] = None
 
 

src/cli_agent_orchestrator/cli/commands/install.py

@@ -64,8 +64,11 @@ def _copy_local_profile_to_store(agent_source: str) -> Optional[str]:
 @click.option(
     "--provider",
     type=click.Choice(PROVIDERS),
-    default=DEFAULT_PROVIDER,
-    help=f"Provider to use (default: {DEFAULT_PROVIDER})",
+    default=None,
+    help=(
+        "Provider to use. Precedence: this flag > the profile's frontmatter "
+        f"'provider:' key > default ({DEFAULT_PROVIDER})."
+    ),
 )
 @click.option(
     "--env",
@@ -77,7 +80,7 @@ def _copy_local_profile_to_store(agent_source: str) -> Optional[str]:
         "Repeatable: --env KEY=VALUE. Example: --env API_TOKEN=my-secret-token."
     ),
 )
-def install(agent_source: str, provider: str, env_vars: tuple[str, ...]) -> None:
+def install(agent_source: str, provider: Optional[str], env_vars: tuple[str, ...]) -> None:
     """
     Install an agent from local store, built-in store, URL, or file path.
 
@@ -138,4 +141,8 @@ def install(agent_source: str, provider: str, env_vars: tuple[str, ...]) -> None
     if result.context_file:
         click.echo(f"✓ Context file: {result.context_file}")
     if result.agent_file:
-        click.echo(f"✓ {provider} agent: {result.agent_file}")
+        # The service resolves flag > frontmatter > default; result.provider
+        # carries the winner (older mocks may omit it, hence the fallback).
+        click.echo(
+            f"✓ {result.provider or provider or DEFAULT_PROVIDER} agent: {result.agent_file}"
+        )

src/cli_agent_orchestrator/ops_mcp_server/server.py

@@ -6,7 +6,7 @@
 from fastmcp import FastMCP
 from pydantic import Field
 
-from cli_agent_orchestrator.constants import API_BASE_URL, DEFAULT_PROVIDER
+from cli_agent_orchestrator.constants import API_BASE_URL
 from cli_agent_orchestrator.ops_mcp_server.models import (
     InstallResult,
     LaunchResult,
@@ -194,9 +194,14 @@ async def get_profile_details(
 async def install_profile(
     source: Annotated[str, Field(description="Agent name or https:// URL to install")],
     provider: Annotated[
-        str,
-        Field(description="Target provider for the installed profile"),
-    ] = DEFAULT_PROVIDER,
+        Optional[str],
+        Field(
+            description=(
+                "Target provider for the installed profile. Omit to honour the "
+                "profile's frontmatter provider, falling back to the default."
+            )
+        ),
+    ] = None,
     env_vars: Annotated[
         Optional[Dict[str, str]],
         Field(description="Optional environment variables to inject before install"),
@@ -224,13 +229,16 @@ async def install_profile(
 
     Args:
         source: Agent name or https:// URL from an allow-listed host
-        provider: Target provider (default: kiro_cli)
+        provider: Target provider. Precedence: explicit value > the profile's
+            frontmatter ``provider:`` key > the server default (kiro_cli)
         env_vars: Optional env vars written to the managed .env before install
 
     Returns:
         InstallResult with success status, file paths, and unresolved env vars
     """
-    body: Dict[str, Any] = {"source": source, "provider": provider}
+    body: Dict[str, Any] = {"source": source}
+    if provider is not None:
+        body["provider"] = provider
     if env_vars:
         body["env_vars"] = env_vars
 

src/cli_agent_orchestrator/services/install_service.py

@@ -1,5 +1,6 @@
 """Service helpers for installing agent profiles."""
 
+import logging
 import os
 import re
 from pathlib import Path
@@ -13,6 +14,7 @@
 from cli_agent_orchestrator.constants import (
     AGENT_CONTEXT_DIR,
     COPILOT_AGENTS_DIR,
+    DEFAULT_PROVIDER,
     KIRO_AGENTS_DIR,
     LOCAL_AGENT_STORE_DIR,
     OPENCODE_AGENTS_DIR,
@@ -40,6 +42,8 @@
 from cli_agent_orchestrator.utils.skill_injection import compose_agent_prompt
 from cli_agent_orchestrator.utils.tool_mapping import resolve_allowed_tools
 
+logger = logging.getLogger(__name__)
+
 
 class InstallResult(BaseModel):
     """Structured result for agent profile installation."""
@@ -51,6 +55,7 @@ class InstallResult(BaseModel):
     agent_file: Optional[str] = None
     unresolved_vars: Optional[List[str]] = None
     source_kind: Optional[Literal["url", "file", "name"]] = None
+    provider: Optional[str] = None
 
 
 # Profile names are used as filesystem path segments under LOCAL_AGENT_STORE_DIR
@@ -232,11 +237,16 @@ def _build_provider_config(
 
 def install_agent(
     source: str,
-    provider: str,
+    provider: Optional[str] = None,
     env_vars: Optional[Dict[str, str]] = None,
 ) -> InstallResult:
     """Install an agent profile for the requested provider.
 
+    ``provider`` resolution follows the same precedence as launch/handoff
+    (see ``resolve_provider``): an explicit argument wins, then the profile's
+    frontmatter ``provider:`` key, then ``DEFAULT_PROVIDER``. Pass ``None``
+    to defer to the profile.
+
     ``source`` must be either an https:// URL on the allowlist or a bare
     profile name matching ``_PROFILE_NAME_RE``. Local ``.md`` file paths
     are deliberately NOT accepted here — the CLI copies user files into
@@ -247,7 +257,10 @@ def install_agent(
     """
     try:
         valid_providers = [provider_type.value for provider_type in ProviderType]
-        if provider not in valid_providers:
+        # An explicit provider is validated up front so bad input fails fast
+        # BEFORE any URL download or env-file mutation. Frontmatter providers
+        # are validated after the profile is parsed (below).
+        if provider is not None and provider not in valid_providers:
             return InstallResult(
                 success=False,
                 message=(
@@ -284,6 +297,25 @@ def install_agent(
         resolved_content = resolve_env_vars(raw_content)
         profile = parse_agent_profile_text(resolved_content, agent_name)
 
+        # No explicit provider — honour the profile's frontmatter ``provider:``
+        # key, mirroring resolve_provider() on the launch/handoff paths. Bogus
+        # frontmatter values warn and fall back to the default; built-in store
+        # profiles carry no frontmatter provider and keep the default.
+        if provider is None:
+            if profile.provider and profile.provider in valid_providers:
+                provider = profile.provider
+            else:
+                if profile.provider:
+                    logger.warning(
+                        "Agent profile '%s' has invalid provider '%s'. "
+                        "Valid providers: %s. Falling back to '%s'.",
+                        profile.name,
+                        profile.provider,
+                        valid_providers,
+                        DEFAULT_PROVIDER,
+                    )
+                provider = DEFAULT_PROVIDER
+
         # Resolve the bundled cao-mcp-server console script to a PATH-independent
         # invocation before materializing provider configs. The
         # configs Kiro/Q write to disk are consumed verbatim by those CLIs, so
@@ -411,6 +443,7 @@ def install_agent(
             agent_file=str(agent_file) if agent_file else None,
             unresolved_vars=unresolved_vars or None,
             source_kind=source_kind,
+            provider=provider,
         )
 
     except requests.RequestException as exc:

test/api/test_api_profiles.py

@@ -106,6 +106,34 @@ def test_returns_install_result(self, client) -> None:
             },
         )
 
+    def test_omitted_provider_forwards_none_for_frontmatter_resolution(self, client) -> None:
+        """Requests without a provider should forward None so the service
+        resolves the profile's frontmatter provider (flag > frontmatter >
+        default precedence, GH #414) — identically to the CLI."""
+        service_result = InstallResult(
+            success=True,
+            message="Agent 'developer' installed successfully",
+            agent_name="developer",
+            provider="claude_code",
+        )
+
+        with patch(
+            "cli_agent_orchestrator.api.main.install_agent",
+            return_value=service_result,
+        ) as mock_install:
+            response = client.post(
+                "/agents/profiles/install",
+                json={"source": "developer"},
+            )
+
+        assert response.status_code == 200
+        assert response.json()["provider"] == "claude_code"
+        mock_install.assert_called_once_with(
+            source="developer",
+            provider=None,
+            env_vars=None,
+        )
+
     def test_returns_400_for_invalid_source(self, client) -> None:
         """Structured service failures should be surfaced as 400s."""
         with patch(

test/cli/commands/test_install.py

@@ -70,6 +70,41 @@ def test_install_success_outputs_result_details(self, runner: CliRunner) -> None
             {"API_TOKEN": "secret-token"},
         )
 
+    def test_install_without_provider_flag_passes_none_and_echoes_resolved_provider(
+        self, runner: CliRunner
+    ) -> None:
+        """Omitting --provider should pass None so the service resolves frontmatter.
+
+        The final summary line must echo the provider the service actually
+        resolved (flag > frontmatter > default), not the CLI default.
+        """
+        service_result = InstallResult(
+            success=True,
+            message="Agent 'developer' installed successfully",
+            agent_name="developer",
+            context_file="/tmp/agent-context/developer.md",
+            agent_file="/tmp/copilot/developer.agent.md",
+            source_kind="name",
+            provider="copilot_cli",
+        )
+
+        with patch(
+            "cli_agent_orchestrator.cli.commands.install.install_agent",
+            return_value=service_result,
+        ) as mock_install:
+            result = runner.invoke(install, ["developer"])
+
+        assert result.exit_code == 0
+        assert "copilot_cli agent: /tmp/copilot/developer.agent.md" in result.output
+        mock_install.assert_called_once_with("developer", None, None)
+
+    def test_install_help_documents_provider_precedence(self, runner: CliRunner) -> None:
+        """--provider help text should document flag > frontmatter > default."""
+        result = runner.invoke(install, ["--help"])
+
+        assert result.exit_code == 0
+        assert "frontmatter" in result.output
+
     def test_install_url_source_prints_download_confirmation(self, runner: CliRunner) -> None:
         """URL installs should print a download confirmation line."""
         service_result = InstallResult(

test/ops_mcp_server/test_server.py

@@ -184,6 +184,31 @@ async def test_install_profile_returns_result_for_url_source(self) -> None:
             json={"source": "https://example.com/remote.md", "provider": "kiro_cli"},
         )
 
+    async def test_install_profile_omits_provider_when_not_explicit(self) -> None:
+        """Omitted provider should be left out of the body so the install API
+        resolves the profile's frontmatter provider (GH #414)."""
+        payload: InstallPayload = {
+            "success": True,
+            "message": "Agent 'developer' installed successfully",
+            "agent_name": "developer",
+            "context_file": "/tmp/developer.md",
+            "agent_file": None,
+            "unresolved_vars": None,
+        }
+        with patch(
+            "cli_agent_orchestrator.ops_mcp_server.server.requests.request",
+            return_value=_response(json_data=payload),
+        ) as mock_request:
+            result = await install_profile("developer")
+
+        assert result == InstallResult(**payload)
+        mock_request.assert_called_once_with(
+            "post",
+            "http://127.0.0.1:9889/agents/profiles/install",
+            params=None,
+            json={"source": "developer"},
+        )
+
     async def test_install_profile_forwards_env_vars(self) -> None:
         """Env var maps should be forwarded to the API install endpoint."""
         payload = {