apm-cli 0.12.2__tar.gz → 0.12.4__tar.gz

{apm_cli-0.12.2/src/apm_cli.egg-info → apm_cli-0.12.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apm-cli
-Version: 0.12.2
+Version: 0.12.4
 Summary: MCP configuration tool
 Author-email: Daniel Meppiel <user@example.com>
 License: MIT License

{apm_cli-0.12.2 → apm_cli-0.12.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.12.2"
+version = "0.12.4"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.10"

{apm_cli-0.12.2 → apm_cli-0.12.4}/src/apm_cli/adapters/client/claude.py

@@ -42,6 +42,12 @@ class ClaudeClientAdapter(CopilotClientAdapter):
     target_name: str = "claude"
     mcp_servers_key: str = "mcpServers"
 
+    # Claude Desktop / Code's mcp config does NOT support runtime env-var
+    # substitution -- the value in ``env`` must be a literal string. This
+    # adapter MUST keep the legacy install-time resolution behaviour.
+    # See #1152 supply-chain analysis.
+    _supports_runtime_env_substitution: bool = False
+
     @staticmethod
     def _normalize_mcp_entry_for_claude_code(entry: dict) -> dict:
         """Normalize a server entry to Claude Code's on-disk shape.

{apm_cli-0.12.2 → apm_cli-0.12.4}/src/apm_cli/adapters/client/copilot.py

@@ -9,11 +9,15 @@ import json
 import os
 import re
 from pathlib import Path
+from typing import ClassVar
+
+import click
 
 from ...core.docker_args import DockerArgsProcessor
 from ...core.token_manager import GitHubTokenManager
 from ...registry.client import SimpleRegistryClient
 from ...registry.integration import RegistryIntegration
+from ...utils.console import _rich_warning
 from ...utils.github_host import is_github_hostname
 from .base import _ENV_VAR_RE, MCPClientAdapter
 
@@ -27,6 +31,67 @@ from .base import _ENV_VAR_RE, MCPClientAdapter
 # per-call cost. ``${input:...}`` is intentionally not matched here.
 _COPILOT_ENV_RE = re.compile(r"<([A-Z_][A-Z0-9_]*)>|" + _ENV_VAR_RE.pattern)
 
+# Detects the legacy ``<VAR>`` placeholder syntax. Used both for translation
+# and for emitting an aggregated deprecation warning, mirroring the analogous
+# pattern in ``vscode.py``.
+_LEGACY_ANGLE_VAR_RE = re.compile(r"<([A-Z_][A-Z0-9_]*)>")
+
+
+def _translate_env_placeholder(value):
+    """Pure-textual translation of env-var placeholders to Copilot CLI's
+    native runtime substitution syntax (``${VAR}``).
+
+    This is the security-critical helper for issue #1152: it MUST NOT read
+    ``os.environ`` and MUST NOT resolve placeholders to their literal values.
+    Copilot CLI resolves ``${VAR}`` from the host environment at server-start
+    time, so APM emits placeholders verbatim rather than baking secrets into
+    ``~/.copilot/mcp-config.json``.
+
+    Translations:
+        ``${env:VAR}``     -> ``${VAR}``     (strip ``env:`` prefix)
+        ``${VAR}``         -> ``${VAR}``     (no-op)
+        ``<VAR>``          -> ``${VAR}``     (legacy syntax migration)
+        ``${VAR:-default}``-> passthrough    (regex doesn't match)
+        ``$VAR`` (bare)    -> passthrough    (regex doesn't match)
+        ``${input:foo}``   -> passthrough    (regex doesn't match)
+        non-string         -> passthrough
+
+    The translation is idempotent: applying it twice produces the same
+    result as applying it once.
+    """
+    if not isinstance(value, str):
+        return value
+
+    def _to_brace(match):
+        # group(1) = legacy <VAR>; group(2) = ${VAR} / ${env:VAR}
+        var_name = match.group(1) or match.group(2)
+        return "${" + var_name + "}"
+
+    return _COPILOT_ENV_RE.sub(_to_brace, value)
+
+
+def _extract_legacy_angle_vars(value):
+    """Return the set of legacy ``<VAR>`` names present in *value*.
+
+    Used to aggregate deprecation warnings across all servers in a single
+    install run, so authors see one helpful list instead of one warning per
+    occurrence.
+    """
+    if not isinstance(value, str):
+        return set()
+    return set(_LEGACY_ANGLE_VAR_RE.findall(value))
+
+
+def _has_env_placeholder(value):
+    """True if *value* is a string containing any recognised env-var
+    placeholder syntax (``${VAR}``, ``${env:VAR}``, or legacy ``<VAR>``).
+    Used to distinguish placeholder-sourced env values (which translate)
+    from hardcoded literal defaults (which stay literal).
+    """
+    if not isinstance(value, str):
+        return False
+    return bool(_COPILOT_ENV_RE.search(value))
+
 
 class CopilotClientAdapter(MCPClientAdapter):
     """Copilot CLI implementation of MCP client adapter.
@@ -41,6 +106,42 @@ class CopilotClientAdapter(MCPClientAdapter):
     target_name: str = "copilot"
     mcp_servers_key: str = "mcpServers"
 
+    # When True, env-var placeholders (``${VAR}``, ``${env:VAR}``, legacy
+    # ``<VAR>``) are translated to Copilot CLI's native runtime-substitution
+    # syntax (``${VAR}``) and emitted into mcp-config.json verbatim. The
+    # secret never touches disk.
+    #
+    # When False, placeholders are resolved at install time against the host
+    # environment and the literal value is baked into the config file
+    # (legacy pre-#1152 behaviour).
+    #
+    # Subclasses (Cursor / Windsurf / OpenCode / Claude / Gemini) override
+    # this to ``False`` until their respective config formats are individually
+    # audited for runtime-substitution support. Critically, Claude Desktop's
+    # config format does NOT support runtime substitution -- it MUST keep
+    # resolving at install time.
+    _supports_runtime_env_substitution: bool = True
+
+    # Process-wide aggregation of legacy ``<VAR>`` offenders, keyed by
+    # adapter class so subclasses (Cursor, etc.) maintain their own
+    # buckets. Populated by ``configure_mcp_server`` and drained by the
+    # post-install summary helper. Class-level so cross-server warnings
+    # work even when a fresh adapter instance is created per dep.
+    _legacy_angle_offenders_by_server: ClassVar[dict] = {}
+    # Process-wide aggregation of env-var keys whose values were previously
+    # baked as plaintext literals on disk and have just been rewritten to
+    # ``${KEY}`` placeholders. Drives the security-improvement notice.
+    _security_upgraded_keys: ClassVar[set] = set()
+    # Process-wide aggregation of env-var names referenced by configs that
+    # are NOT exported in the current shell. Drives the post-install
+    # actionable warning that lists vars the user must export before
+    # launching ``gh copilot``.
+    _unset_env_keys_by_server: ClassVar[dict] = {}
+    # Guard so the post-install summary is emitted at most once per CLI
+    # invocation, regardless of how many ``configure_mcp_server`` calls
+    # contributed to the aggregation buckets.
+    _install_run_summary_emitted: ClassVar[bool] = False
+
     def __init__(
         self,
         registry_url=None,
@@ -61,6 +162,14 @@ class CopilotClientAdapter(MCPClientAdapter):
         super().__init__(project_root=project_root, user_scope=user_scope)
         self.registry_client = SimpleRegistryClient(registry_url)
         self.registry_integration = RegistryIntegration(registry_url)
+        # Per-server tracking of placeholder-sourced env-var keys, populated
+        # during ``_format_server_config`` and consumed by the post-install
+        # summary line. Keys: env-var names; never holds resolved values.
+        self._last_env_placeholder_keys = set()
+        # Per-server collection of legacy ``<VAR>`` offenders, populated by
+        # the resolution helpers and consumed by ``configure_mcp_server`` to
+        # feed the aggregated deprecation warning.
+        self._last_legacy_angle_vars = set()
 
     def get_config_path(self):
         """Get the path to the Copilot CLI MCP configuration file.
@@ -154,6 +263,26 @@ class CopilotClientAdapter(MCPClientAdapter):
                 print(f"Error: MCP server '{server_url}' not found in registry")
                 return False
 
+            # Reset per-server tracking before formatting (so the per-server
+            # summary line and aggregated diagnostics reflect this server only).
+            self._last_env_placeholder_keys = set()
+            self._last_legacy_angle_vars = set()
+
+            # Detect security upgrade: was the previous on-disk config for
+            # this server holding literal (resolved) values for env keys
+            # we are about to replace with ${KEY} placeholders? If so,
+            # remember the affected keys for the post-install notice. We
+            # snapshot BEFORE writing the new config.
+            previously_baked_keys = set()
+            previously_baked_headers = False
+            if self._supports_runtime_env_substitution:
+                previously_baked_keys, previously_baked_headers = (
+                    self._collect_previously_baked_keys(server_url, server_name)
+                )
+
+            # Generate server configuration with environment and runtime variable resolution
+            server_config = self._format_server_config(server_info, env_overrides, runtime_vars)
+
             # Determine the server name for configuration key
             if server_name:
                 # Use explicitly provided server name
@@ -168,19 +297,193 @@ class CopilotClientAdapter(MCPClientAdapter):
                     # Fallback to full server_url if no slash
                     config_key = server_url
 
-            # Generate server configuration with environment and runtime variable resolution
-            server_config = self._format_server_config(server_info, env_overrides, runtime_vars)
-
             # Update configuration using the chosen key
             self.update_config({config_key: server_config})
 
-            print(f"Successfully configured MCP server '{config_key}' for {self._client_label}")
+            # Aggregate diagnostics for the post-install summary.
+            if self._supports_runtime_env_substitution:
+                if self._last_legacy_angle_vars:
+                    self._legacy_angle_offenders_by_server[config_key] = set(
+                        self._last_legacy_angle_vars
+                    )
+                # Only flag a security upgrade when the previously baked keys
+                # actually overlap with what we are now placeholderizing -- OR
+                # when the previous on-disk state had baked HTTP header
+                # literals (which don't expose env-var names directly, so we
+                # surface every newly-placeholderised key for this server).
+                upgraded = previously_baked_keys & self._last_env_placeholder_keys
+                if previously_baked_headers and self._last_env_placeholder_keys:
+                    upgraded = upgraded | self._last_env_placeholder_keys
+                if upgraded:
+                    self._security_upgraded_keys.update(upgraded)
+
+            # Per-server install line with env-var summary parenthetical.
+            self._emit_install_summary(config_key, server_config)
             return True
 
         except Exception as e:
             print(f"Error configuring MCP server: {e}")
             return False
 
+    def _collect_previously_baked_keys(self, server_url, server_name):
+        """Return ``(env_keys, headers_were_baked)`` for the existing on-disk
+        entry: the set of env-block keys whose values are literal
+        (non-placeholder) strings, and a flag indicating whether the headers
+        block contained any literal values. Together these drive the
+        security-improvement notice. Headers don't expose env-var names
+        directly, so the caller unions current-write placeholder keys when
+        ``headers_were_baked`` is True.
+        """
+        try:
+            current = self.get_current_config()
+        except Exception:
+            return set(), False
+        servers = current.get("mcpServers") or {}
+        # Match the same key resolution rule used below.
+        if server_name:
+            key = server_name
+        elif "/" in server_url:
+            key = server_url.split("/")[-1]
+        else:
+            key = server_url
+        existing = servers.get(key)
+        if not isinstance(existing, dict):
+            return set(), False
+        baked_env_keys = set()
+        env_block = existing.get("env") or {}
+        if isinstance(env_block, dict):
+            for k, v in env_block.items():
+                if isinstance(v, str) and v.strip() and not _has_env_placeholder(v):
+                    baked_env_keys.add(k)
+        headers_were_baked = False
+        headers_block = existing.get("headers") or {}
+        if isinstance(headers_block, dict):
+            for v in headers_block.values():
+                if isinstance(v, str) and v.strip() and not _has_env_placeholder(v):
+                    headers_were_baked = True
+                    break
+        return baked_env_keys, headers_were_baked
+
+    def _emit_install_summary(self, config_key, server_config):
+        """Record env-var references for the post-install aggregated
+        summary. No per-server line is emitted here; the integrator's
+        tree (``|  +  {name} -> Copilot (configured)``) is the success
+        signal. The summary references env-var names only -- never their
+        values.
+        """
+        if not self._supports_runtime_env_substitution:
+            return
+        keys = set(self._last_env_placeholder_keys)
+        if isinstance(server_config, dict):
+            for block_key in ("env", "headers"):
+                block = server_config.get(block_key)
+                if not isinstance(block, dict):
+                    continue
+                for value in block.values():
+                    if isinstance(value, str):
+                        for match in _ENV_VAR_RE.finditer(value):
+                            keys.add(match.group(1))
+        unset = sorted(name for name in keys if not os.environ.get(name))
+        if unset:
+            self.__class__._unset_env_keys_by_server.setdefault(config_key, []).extend(
+                u
+                for u in unset
+                if u not in self.__class__._unset_env_keys_by_server.get(config_key, [])
+            )
+
+    @classmethod
+    def emit_install_run_summary(cls):
+        """Emit aggregated cross-server diagnostics at the end of an install
+        run. Idempotent: subsequent calls within the same process are no-ops.
+
+        Three diagnostics are emitted (when applicable):
+
+        1. Security improvement notice -- when the install rewrote
+           previously baked literal env values to runtime placeholders.
+           Emitted as a warning because it is an action item (the user
+           must export the affected vars).
+        2. Aggregated unset-env warning -- when one or more configured
+           servers reference env vars that are not currently exported.
+           Includes a copy-pasteable ``export`` hint.
+        3. Aggregated legacy ``<VAR>`` deprecation warning -- one line
+           naming all affected servers, mirroring the established VS Code
+           adapter pattern.
+
+        State is drained after emission so a subsequent install run in
+        the same process (e.g. tests) starts clean.
+        """
+        if cls._install_run_summary_emitted:
+            return
+
+        # Visual separator from the install tree's closing line so the
+        # post-tree summary block reads as a distinct section.
+        emitted_any = False
+
+        def _emit_separator_once():
+            nonlocal emitted_any
+            if not emitted_any:
+                click.echo("")
+                emitted_any = True
+
+        if cls._security_upgraded_keys:
+            visible = sorted(cls._security_upgraded_keys)
+            count = len(visible)
+            noun = "variable" if count == 1 else "variables"
+            affected = ", ".join(visible)
+            _emit_separator_once()
+            _rich_warning(
+                f"Security improvement: {count} environment {noun} previously stored as "
+                f"plaintext in the Copilot config are now resolved at runtime.\n"
+                f"    Affected: {affected}\n"
+                f"    Ensure these are exported in your shell before running 'gh copilot'",
+                symbol="warning",
+            )
+        if cls._unset_env_keys_by_server:
+            all_unset: set[str] = set()
+            for names in cls._unset_env_keys_by_server.values():
+                all_unset.update(names)
+            sorted_unset = sorted(all_unset)
+            export_hint = " ".join(f"{name}=..." for name in sorted_unset)
+            count = len(sorted_unset)
+            noun = "variable" if count == 1 else "variables"
+            _emit_separator_once()
+            _rich_warning(
+                f"Copilot CLI will resolve {count} environment {noun} at runtime "
+                f"that {'is' if count == 1 else 'are'} not currently set: "
+                f"{', '.join(sorted_unset)}.\n"
+                f"    Export {'it' if count == 1 else 'them'} in your shell before "
+                f"running 'gh copilot', e.g.:\n"
+                f"      export {export_hint}",
+                symbol="warning",
+            )
+        # Deprecation notice is informational housekeeping (not a runtime
+        # blocker), but it ships unguarded for now so legacy <VAR> usage
+        # remains visible until the v1.0 removal. If --quiet gating is
+        # added in future, the unset-env and security warnings above must
+        # remain unsuppressible because they describe action-required state.
+        if cls._legacy_angle_offenders_by_server:
+            servers = sorted(cls._legacy_angle_offenders_by_server.keys())
+            count = len(servers)
+            noun = "server" if count == 1 else "servers"
+            _emit_separator_once()
+            _rich_warning(
+                f"Deprecated: <VAR> placeholder syntax used in {count} {noun} "
+                f"({', '.join(servers)}). Migrate to ${{VAR}} in apm.yml. "
+                f"<VAR> support will be removed in v1.0.",
+                symbol="warning",
+            )
+        cls._install_run_summary_emitted = True
+
+    @classmethod
+    def reset_install_run_state(cls):
+        """Reset the process-wide aggregation buckets. Intended for tests
+        and for explicitly starting a new install run within the same
+        process."""
+        cls._legacy_angle_offenders_by_server = {}
+        cls._security_upgraded_keys = set()
+        cls._unset_env_keys_by_server = {}
+        cls._install_run_summary_emitted = False
+
     def _format_server_config(self, server_info, env_overrides=None, runtime_vars=None):
         """Format server information into Copilot CLI MCP configuration format.
 
@@ -202,14 +505,27 @@ class CopilotClientAdapter(MCPClientAdapter):
             "id": server_info.get("id", ""),  # Add registry UUID for conflict detection
         }
 
-        # Self-defined stdio deps carry raw command/args  -- use directly
+        # Self-defined stdio deps carry raw command/args  -- use directly,
+        # but route values through the env-var translation/resolution pipeline
+        # so secrets are not baked into the persisted config when the harness
+        # supports runtime substitution (Copilot CLI).
         raw = server_info.get("_raw_stdio")
         if raw:
             config["command"] = raw["command"]
-            config["args"] = raw["args"]
+            resolved_env_for_args = {}
             if raw.get("env"):
-                config["env"] = raw["env"]
+                resolved_env_for_args = self._resolve_environment_variables(
+                    raw["env"], env_overrides=env_overrides
+                )
+                config["env"] = resolved_env_for_args
                 self._warn_input_variables(raw["env"], server_info.get("name", ""), "Copilot CLI")
+            args = raw.get("args") or []
+            config["args"] = [
+                self._resolve_variable_placeholders(arg, resolved_env_for_args, runtime_vars)
+                if isinstance(arg, str)
+                else arg
+                for arg in args
+            ]
             # Apply tools override if present
             tools_override = server_info.get("_apm_tools_override")
             if tools_override:
@@ -385,15 +701,93 @@ class CopilotClientAdapter(MCPClientAdapter):
         return config
 
     def _resolve_environment_variables(self, env_vars, env_overrides=None):
-        """Resolve environment variables to actual values.
+        """Resolve (or translate) declared environment variables.
+
+        Behaviour depends on ``self._supports_runtime_env_substitution``:
+
+        - True (Copilot CLI default): each declared env var ``NAME`` gets a
+          ``${NAME}`` placeholder that Copilot CLI resolves at server-start
+          from the host environment. Hardcoded literal defaults
+          (``GITHUB_TOOLSETS``, ``GITHUB_DYNAMIC_TOOLSETS``) stay literal
+          because they are not secrets and provide essential server
+          configuration. The host environment is NOT read; secrets never
+          touch disk. See issue #1152 for context.
+
+        - False (legacy / sibling-adapter behaviour): resolve each variable
+          to its literal value via ``env_overrides`` -> ``os.environ`` ->
+          optional interactive prompt, baking the result into the config.
 
         Args:
-            env_vars (list): List of environment variable definitions from server info.
-            env_overrides (dict, optional): Pre-collected environment variable overrides.
+            env_vars (list): List of environment variable definitions from
+                server info (each item is ``{name, description, required}``).
+            env_overrides (dict, optional): Pre-collected environment
+                variable overrides. Ignored in translate mode.
 
         Returns:
-            dict: Dictionary of resolved environment variables.
+            dict: ``{name: value}`` -- placeholder string in translate mode,
+            literal value in legacy mode.
         """
+        # Hardcoded literal defaults that supply essential server behaviour
+        # rather than secrets. These stay literal in translate mode so that
+        # tool-selection still works without a user export step.
+        default_github_env = {"GITHUB_TOOLSETS": "context", "GITHUB_DYNAMIC_TOOLSETS": "1"}
+
+        # Self-defined stdio deps pass ``env`` as a plain dict
+        # ({NAME: value-or-placeholder}); registry-sourced deps pass a list
+        # of {name, description, required} dicts. Translate-mode handling
+        # for the dict shape: each value is either already a placeholder
+        # (translate it to the canonical ${VAR} form) or a literal (record
+        # the key as a placeholder reference and emit ${NAME} so the
+        # value never lands on disk). See issue #1152.
+        if isinstance(env_vars, dict) and self._supports_runtime_env_substitution:
+            translated = {}
+            placeholder_keys = []
+            for name, raw_value in env_vars.items():
+                if not name:
+                    continue
+                if not isinstance(raw_value, str):
+                    translated[name] = raw_value
+                    continue
+                if _has_env_placeholder(raw_value):
+                    self._last_legacy_angle_vars.update(_extract_legacy_angle_vars(raw_value))
+                    translated[name] = _translate_env_placeholder(raw_value)
+                    # Record every ${VAR} in the translated value (handles
+                    # both ${env:VAR} -> ${VAR} and bare ${VAR} cases).
+                    for match in _ENV_VAR_RE.finditer(translated[name]):
+                        placeholder_keys.append(match.group(1))
+                elif name in default_github_env and raw_value == default_github_env[name]:
+                    translated[name] = raw_value
+                else:
+                    # Literal value present in apm.yml -- replace with a
+                    # runtime placeholder so the secret never touches disk.
+                    translated[name] = "${" + name + "}"
+                    placeholder_keys.append(name)
+            self._last_env_placeholder_keys = set(placeholder_keys)
+            return translated
+
+        if self._supports_runtime_env_substitution:
+            resolved = {}
+            placeholder_keys = []
+            for env_var in env_vars:
+                if not isinstance(env_var, dict):
+                    continue
+                name = env_var.get("name", "")
+                if not name:
+                    continue
+                if name in default_github_env:
+                    # Non-secret literal default -- preserve as-is.
+                    resolved[name] = default_github_env[name]
+                else:
+                    # Emit a runtime-substitution placeholder; Copilot CLI
+                    # resolves ``${NAME}`` from the host environment at
+                    # server-start. APM never reads or stores the value.
+                    resolved[name] = "${" + name + "}"
+                    placeholder_keys.append(name)
+            # Record for the post-install summary line and the
+            # security-improvement notice.
+            self._last_env_placeholder_keys = set(placeholder_keys)
+            return resolved
+
         import os
         import sys
 
@@ -416,10 +810,6 @@ class CopilotClientAdapter(MCPClientAdapter):
         if not is_interactive:
             skip_prompting = True
 
-        # Add default GitHub MCP server environment variables for essential functionality first
-        # This ensures variables have defaults when user provides empty values or they're optional
-        default_github_env = {"GITHUB_TOOLSETS": "context", "GITHUB_DYNAMIC_TOOLSETS": "1"}
-
         # Track which variables were explicitly provided with empty values (user wants defaults)
         empty_value_vars = set()
         if env_overrides:
@@ -465,16 +855,42 @@ class CopilotClientAdapter(MCPClientAdapter):
         return resolved
 
     def _resolve_env_variable(self, name, value, env_overrides=None):
-        """Resolve a single environment variable value.
+        """Resolve (or translate) a single environment variable value.
+
+        Behaviour depends on ``self._supports_runtime_env_substitution``:
+
+        - True (Copilot CLI default): translate placeholders to Copilot CLI's
+          native runtime substitution syntax (``${VAR}``). The host
+          environment is NOT read; the secret never touches disk. See issue
+          #1152 for context. Legacy ``<VAR>`` offenders are tracked for the
+          aggregated deprecation warning emitted by
+          ``configure_mcp_server``.
+
+        - False (legacy / sibling-adapter behaviour): resolve placeholders
+          to literal values via ``env_overrides`` -> ``os.environ`` ->
+          optional interactive prompt, baking the result into the config.
 
         Args:
             name (str): Environment variable name.
             value (str): Environment variable value or placeholder.
-            env_overrides (dict, optional): Pre-collected environment variable overrides.
+            env_overrides (dict, optional): Pre-collected environment
+                variable overrides. Ignored in translate mode.
 
         Returns:
-            str: Resolved environment variable value.
+            str: Translated placeholder (translate mode) or resolved
+            literal value (legacy mode).
         """
+        if self._supports_runtime_env_substitution:
+            # Track legacy <VAR> offenders for the aggregated deprecation
+            # warning. Translation itself is a pure-textual rewrite.
+            self._last_legacy_angle_vars.update(_extract_legacy_angle_vars(value))
+            # Track env-var names referenced via this header/value so the
+            # security-upgrade detector and per-server summary can see
+            # them (the env-block path tracks via _resolve_environment_variables).
+            for match in _ENV_VAR_RE.finditer(value):
+                self._last_env_placeholder_keys.add(match.group(1))
+            return _translate_env_placeholder(value)
+
         import sys
 
         from rich.prompt import Prompt
@@ -683,15 +1099,31 @@ class CopilotClientAdapter(MCPClientAdapter):
         return processed
 
     def _resolve_variable_placeholders(self, value, resolved_env, runtime_vars):
-        """Resolve both environment and runtime variable placeholders in values.
+        """Resolve runtime template variables and translate or resolve env-var
+        placeholders in argument strings.
+
+        Behaviour depends on ``self._supports_runtime_env_substitution``:
+
+        - True (Copilot CLI default): env-var placeholders (``<VAR>``,
+          ``${VAR}``, ``${env:VAR}``) are translated to ``${VAR}`` for
+          runtime substitution by Copilot CLI. APM template variables
+          (``{runtime_var}``) are still resolved at install time because
+          they are an APM-internal concept Copilot cannot interpret.
+
+        - False (legacy / sibling-adapter behaviour): legacy ``<VAR>``
+          placeholders are resolved against ``resolved_env`` (the dict of
+          literal env-var values), and ``{runtime_var}`` against
+          ``runtime_vars``. Newer ``${VAR}`` / ``${env:VAR}`` syntaxes are
+          left as-is for backward compatibility.
 
         Args:
-            value (str): Value that may contain placeholders like <TOKEN_NAME> or {ado_org}
-            resolved_env (dict): Dictionary of resolved environment variables.
+            value (str): Value that may contain placeholders.
+            resolved_env (dict): Dictionary of resolved env vars (legacy
+                mode) or placeholder strings (translate mode).
             runtime_vars (dict): Dictionary of resolved runtime variables.
 
         Returns:
-            str: Processed value with actual variable values.
+            str: Processed value with placeholders translated or resolved.
         """
         import re
 
@@ -700,23 +1132,33 @@ class CopilotClientAdapter(MCPClientAdapter):
 
         processed = str(value)
 
-        # Replace <TOKEN_NAME> with actual values from resolved_env (for Docker env vars)
-        env_pattern = r"<([A-Z_][A-Z0-9_]*)>"
-
-        def replace_env_var(match):
-            env_name = match.group(1)
-            return resolved_env.get(env_name, match.group(0))  # Return original if not found
-
-        processed = re.sub(env_pattern, replace_env_var, processed)
-
-        # Replace {runtime_var} with actual values from runtime_vars (for NPM args)
-        runtime_pattern = r"\{([a-zA-Z_][a-zA-Z0-9_]*)\}"
-
-        def replace_runtime_var(match):
-            var_name = match.group(1)
-            return runtime_vars.get(var_name, match.group(0))  # Return original if not found
-
-        processed = re.sub(runtime_pattern, replace_runtime_var, processed)
+        if self._supports_runtime_env_substitution:
+            # Track legacy <VAR> offenders before translating them away.
+            self._last_legacy_angle_vars.update(_extract_legacy_angle_vars(processed))
+            # Translate all three env-var placeholder syntaxes to ${VAR}.
+            processed = _translate_env_placeholder(processed)
+        else:
+            # Replace <TOKEN_NAME> with actual values from resolved_env (for Docker env vars)
+            env_pattern = r"<([A-Z_][A-Z0-9_]*)>"
+
+            def replace_env_var(match):
+                env_name = match.group(1)
+                return resolved_env.get(env_name, match.group(0))  # Return original if not found
+
+            processed = re.sub(env_pattern, replace_env_var, processed)
+
+        # Replace {runtime_var} with actual values from runtime_vars (for NPM args).
+        # Negative lookbehind on `$` so we never re-substitute inside an already-translated
+        # ${VAR} env placeholder (the brace is part of a Copilot CLI runtime substitution,
+        # not an APM template variable).
+        if runtime_vars:
+            runtime_pattern = r"(?<!\$)\{([a-zA-Z_][a-zA-Z0-9_]*)\}"
+
+            def replace_runtime_var(match):
+                var_name = match.group(1)
+                return runtime_vars.get(var_name, match.group(0))
+
+            processed = re.sub(runtime_pattern, replace_runtime_var, processed)
 
         return processed