google-agents-cli 1.8.0__tar.gz → 1.10.0__tar.gz

{google_agents_cli-1.8.0 → google_agents_cli-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 1.8.0
+Version: 1.10.0
 Summary: Agents CLI — Agent Development Lifecycle toolchain for ADK
 Author-email: Google LLC <agents-cli-dev-pypi@google.com>
 Requires-Python: >=3.11
@@ -13,7 +13,7 @@ Requires-Dist: click>=8.1.8,<9
 Requires-Dist: PyYAML>=6.0.2,<7
 Requires-Dist: cookiecutter>=2.6.0,<3
 Requires-Dist: jinja2>=3.1.0
-Requires-Dist: google-cloud-aiplatform[evaluation]>=1.165.0,<2
+Requires-Dist: google-cloud-aiplatform[evaluation]>=2.2.0,<3
 Requires-Dist: google-cloud-resource-manager>=1.12.0
 Requires-Dist: google-auth[pyopenssl]>=2.47.0
 Requires-Dist: pyopenssl<26.2
@@ -42,7 +42,7 @@ Provides-Extra: lint
 <div align="center">
   <img src="https://raw.githubusercontent.com/google/agents-cli/main/docs/src/assets/logo_sm.png" alt="agents-cli logo" width="120" />
   <h1><code>agents-cli</code></h1>
-  <p>The CLI and skills for building agents on Gemini Enterprise Agent Platform.</p>
+  <p>The CLI and skills for building agents on Gemini platform.</p>
 
   <p>
     <a href="#get-started">Get Started</a> &nbsp;&nbsp;|&nbsp;&nbsp;
@@ -60,7 +60,7 @@ Provides-Extra: lint
 
 Turn your favorite coding assistant into an expert at building and deploying agents on Google Cloud.
 
-**Agents CLI in Agent Platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.
+**Agents CLI in Gemini platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.
 
 **Works seamlessly with:**
 [Antigravity CLI](https://antigravity.google/) &nbsp;•&nbsp; [Claude Code](https://docs.anthropic.com/en/docs/claude-code) &nbsp;•&nbsp; [Codex](https://github.com/openai/codex) &nbsp;•&nbsp; *and any other coding agent.*
@@ -106,8 +106,8 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `google-agents-cli-adk-code` | ADK Python API — agents, tools, orchestration, callbacks, state |
 | `google-agents-cli-scaffold` | Project scaffolding — `create`, `enhance`, `upgrade` |
 | `google-agents-cli-eval` | Evaluation methodology — metrics, datasets, LLM-as-judge, adaptive rubrics |
-| `google-agents-cli-deploy` | Deployment — [Agent Runtime](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale), [Cloud Run](https://cloud.google.com/run), [GKE](https://cloud.google.com/kubernetes-engine), CI/CD, secrets |
-| `google-agents-cli-publish` | Gemini Enterprise registration |
+| `google-agents-cli-deploy` | Deployment — [Agent Runtime in Gemini platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale), [Cloud Run](https://cloud.google.com/run), [GKE](https://cloud.google.com/kubernetes-engine), CI/CD, secrets |
+| `google-agents-cli-publish` | Gemini registration |
 | `google-agents-cli-observability` | Observability — Cloud Trace, logging, third-party integrations |
 
 ---
@@ -120,7 +120,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli create <name>` | Create a new agent project |
 | `agents-cli eval run` | Run the agent over the eval dataset and grade the traces |
 | `agents-cli deploy` | Deploy to Google Cloud |
-| `agents-cli publish gemini-enterprise` | Register with Gemini Enterprise |
+| `agents-cli publish gemini` | Register with Gemini |
 
 <details>
 <summary>See all commands</summary>
@@ -148,7 +148,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli eval optimize` | Auto-tune agent prompts using eval data |
 | **Deploy & Publish** | |
 | `agents-cli deploy` | Deploy to Google Cloud |
-| `agents-cli publish gemini-enterprise` | Register with Gemini Enterprise |
+| `agents-cli publish gemini` | Register with Gemini |
 | `agents-cli infra single-project` | Provision single-project infrastructure |
 | `agents-cli infra cicd` | Set up CI/CD pipeline + staging/prod infrastructure |
 | **Other** | |
@@ -210,10 +210,7 @@ See the [contributing guide](CONTRIBUTING.md) for details.
 
 ## Telemetry
 
-> **Note:** Telemetry is experimental and off by default. It only runs when
-> enabled with `AGENTS_CLI_EXPERIMENTS='{"cli_telemetry": true}'`.
-
-`agents-cli` can emit a single usage signal per command invocation to help
+By default, `agents-cli` emits a single usage signal per command invocation to help
 improve the tool and better understand how it's used. Each signal
 is a structured log entry written to **your own Google Cloud project**:
 `GOOGLE_CLOUD_PROJECT`, or else the default project of your Application Default

{google_agents_cli-1.8.0 → google_agents_cli-1.10.0}/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <img src="https://raw.githubusercontent.com/google/agents-cli/main/docs/src/assets/logo_sm.png" alt="agents-cli logo" width="120" />
   <h1><code>agents-cli</code></h1>
-  <p>The CLI and skills for building agents on Gemini Enterprise Agent Platform.</p>
+  <p>The CLI and skills for building agents on Gemini platform.</p>
 
   <p>
     <a href="#get-started">Get Started</a> &nbsp;&nbsp;|&nbsp;&nbsp;
@@ -19,7 +19,7 @@
 
 Turn your favorite coding assistant into an expert at building and deploying agents on Google Cloud.
 
-**Agents CLI in Agent Platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.
+**Agents CLI in Gemini platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.
 
 **Works seamlessly with:**
 [Antigravity CLI](https://antigravity.google/) &nbsp;•&nbsp; [Claude Code](https://docs.anthropic.com/en/docs/claude-code) &nbsp;•&nbsp; [Codex](https://github.com/openai/codex) &nbsp;•&nbsp; *and any other coding agent.*
@@ -65,8 +65,8 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `google-agents-cli-adk-code` | ADK Python API — agents, tools, orchestration, callbacks, state |
 | `google-agents-cli-scaffold` | Project scaffolding — `create`, `enhance`, `upgrade` |
 | `google-agents-cli-eval` | Evaluation methodology — metrics, datasets, LLM-as-judge, adaptive rubrics |
-| `google-agents-cli-deploy` | Deployment — [Agent Runtime](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale), [Cloud Run](https://cloud.google.com/run), [GKE](https://cloud.google.com/kubernetes-engine), CI/CD, secrets |
-| `google-agents-cli-publish` | Gemini Enterprise registration |
+| `google-agents-cli-deploy` | Deployment — [Agent Runtime in Gemini platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale), [Cloud Run](https://cloud.google.com/run), [GKE](https://cloud.google.com/kubernetes-engine), CI/CD, secrets |
+| `google-agents-cli-publish` | Gemini registration |
 | `google-agents-cli-observability` | Observability — Cloud Trace, logging, third-party integrations |
 
 ---
@@ -79,7 +79,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli create <name>` | Create a new agent project |
 | `agents-cli eval run` | Run the agent over the eval dataset and grade the traces |
 | `agents-cli deploy` | Deploy to Google Cloud |
-| `agents-cli publish gemini-enterprise` | Register with Gemini Enterprise |
+| `agents-cli publish gemini` | Register with Gemini |
 
 <details>
 <summary>See all commands</summary>
@@ -107,7 +107,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli eval optimize` | Auto-tune agent prompts using eval data |
 | **Deploy & Publish** | |
 | `agents-cli deploy` | Deploy to Google Cloud |
-| `agents-cli publish gemini-enterprise` | Register with Gemini Enterprise |
+| `agents-cli publish gemini` | Register with Gemini |
 | `agents-cli infra single-project` | Provision single-project infrastructure |
 | `agents-cli infra cicd` | Set up CI/CD pipeline + staging/prod infrastructure |
 | **Other** | |
@@ -169,10 +169,7 @@ See the [contributing guide](CONTRIBUTING.md) for details.
 
 ## Telemetry
 
-> **Note:** Telemetry is experimental and off by default. It only runs when
-> enabled with `AGENTS_CLI_EXPERIMENTS='{"cli_telemetry": true}'`.
-
-`agents-cli` can emit a single usage signal per command invocation to help
+By default, `agents-cli` emits a single usage signal per command invocation to help
 improve the tool and better understand how it's used. Each signal
 is a structured log entry written to **your own Google Cloud project**:
 `GOOGLE_CLOUD_PROJECT`, or else the default project of your Application Default

{google_agents_cli-1.8.0 → google_agents_cli-1.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-agents-cli"
-version = "1.8.0"
+version = "1.10.0"
 description = "Agents CLI — Agent Development Lifecycle toolchain for ADK"
 readme = "README.md"
 license = "Apache-2.0"
@@ -16,7 +16,7 @@ dependencies = [
   "PyYAML>=6.0.2,<7",
   "cookiecutter>=2.6.0,<3",
   "jinja2>=3.1.0",
-  "google-cloud-aiplatform[evaluation]>=1.165.0,<2",
+  "google-cloud-aiplatform[evaluation]>=2.2.0,<3",
   "google-cloud-resource-manager>=1.12.0",
   "google-auth[pyopenssl]>=2.47.0",
   # pyOpenSSL 26.2 forbids mutating a used SSL Context; urllib3 does it per
@@ -135,10 +135,14 @@ ignore = ["E501", "C901", "RUF001", "UP036", "RUF067", "RUF069"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**/*.py" = ["PLR0917"]
+# The only module allowed to import private Agent Platform SDK modules; keep in
+# sync with ALLOWED_PRIVATE_IMPORT_FILES in tools/ci/check_private_imports.py.
+"src/google/agents/cli/_sdk_compat.py" = ["TID251"]
 
 [tool.ruff.lint.flake8-tidy-imports.banned-api]
 "rich.console.Console" = { msg = "Use `google.agents.cli._output.Console` instead to ensure project-wide defaults (soft_wrap=True) are applied." }
 "agentplatform.Client" = { msg = "Use `google.agents.cli._agent_platform.AgentPlatformClient` instead, so the client retries throttled requests." }
+"agentplatform._genai" = { msg = "Private SDK module that can change without notice. Use `types` from `google.agents.cli._agent_platform_types` for SDK types, and add any other private SDK use to `google.agents.cli._sdk_compat`." }
 
 [tool.ruff.lint.pylint]
 max-positional-args = 5

{google_agents_cli-1.8.0 → google_agents_cli-1.10.0}/src/google/agents/cli/_agent_platform.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Shared construction of the Agent Platform SDK client."""
+"""Shared construction of the Gemini platform SDK client."""
 
 from __future__ import annotations
 
@@ -21,7 +21,7 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
     import agentplatform
 
-# Retry options applied to every Agent Platform client the CLI builds. Leaving
+# Retry options applied to every Gemini platform client the CLI builds. Leaving
 # http_status_codes unset keeps the SDK's default retryable set (408/429/500/502/503/504);
 # waits are roughly 1s, 2s, 4s, 8s (full-jittered).
 RETRY_OPTIONS: dict[str, Any] = {
@@ -31,7 +31,7 @@ RETRY_OPTIONS: dict[str, Any] = {
 
 
 class AgentPlatformClient:
-    """Agent Platform client configured with CLI-wide defaults (e.g. retries on transient errors).
+    """Gemini platform client configured with CLI-wide defaults (e.g. retries on transient errors).
 
     Retries are opt-in in the underlying SDK, so constructing ``agentplatform.Client``
     directly runs without them. A ruff rule enforces using this wrapper instead.

google_agents_cli-1.10.0/src/google/agents/cli/_agent_platform_types.py

@@ -0,0 +1,23 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Gemini platform SDK types.
+
+Use ``types.EvalCase``, ``types.evals.AgentEvent``, etc. from here rather than
+importing ``agentplatform._genai`` directly. ``_sdk_compat`` resolves them.
+"""
+
+from google.agents.cli._sdk_compat import types
+
+__all__ = ["types"]

{google_agents_cli-1.8.0 → google_agents_cli-1.10.0}/src/google/agents/cli/_click.py

@@ -65,6 +65,7 @@ class LazyGroup(click.Group):
         # name -> experiment label
         self._experiment_gates: dict[str, str] = {}
         self._overrides: dict[str, click.Command] = {}
+        self._hidden: set[str] = set()
 
     def add_lazy_command(
         self,
@@ -72,6 +73,7 @@ class LazyGroup(click.Group):
         import_path: str,
         short_help: str,
         experiment: str | None = None,
+        hidden: bool = False,
     ) -> None:
         """Register a subcommand for lazy loading.
 
@@ -83,10 +85,20 @@ class LazyGroup(click.Group):
         not at this registration call: `main` is built once at import, so
         guarding registration would freeze visibility before a unit test could
         override the experiment.
+
+        `hidden` keeps a command invocable but out of --help and the docs, e.g.
+        an old name kept as an alias after a rename.
         """
         self._lazy_commands[name] = (import_path, short_help)
         if experiment is not None:
             self._experiment_gates[name] = experiment
+        if hidden:
+            self._hidden.add(name)
+
+    @property
+    def hidden_commands(self) -> frozenset[str]:
+        """Names registered with `hidden=True`: invocable, but not listed."""
+        return frozenset(self._hidden)
 
     def _is_visible(self, name: str) -> bool:
         """True if `name` is not hidden via experiment."""
@@ -100,7 +112,7 @@ class LazyGroup(click.Group):
             set(super().list_commands(ctx))
             | set(self._lazy_commands)
             | set(self._overrides)
-        )
+        ) - self._hidden
         return sorted(filter(self._is_visible, names))
 
     def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:

{google_agents_cli-1.8.0 → google_agents_cli-1.10.0}/src/google/agents/cli/_experiments.py

@@ -28,9 +28,6 @@ class Experiment(NamedTuple):
 _REGISTRY: dict[str, Experiment] = {
     # Hides the `build` command until Go (compiled-language) support launches.
     "build_command": Experiment("build_command", bool, True),
-    # Gates CLI usage telemetry (see _telemetry.py). Off by default
-    # during validation. Users can opt out via DO_NOT_TRACK / AGENTS_CLI_TELEMETRY.
-    "cli_telemetry": Experiment("cli_telemetry", bool, False),
 }
 
 

google_agents_cli-1.10.0/src/google/agents/cli/_fs.py

@@ -0,0 +1,95 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""File system helpers for agents CLI."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import shutil
+import stat
+from pathlib import Path
+
+
+def delete_folder(folder: Path) -> None:
+    """Delete `folder`, even when it holds read-only folders; warn when it cannot."""
+    make_folders_writable(folder)
+    shutil.rmtree(folder, ignore_errors=True)
+    if folder.exists() or folder.is_symlink():
+        logging.warning("Could not delete %s; delete it by hand.", folder)
+
+
+def delete_path(path: Path) -> None:
+    """Delete `path`; unlink a link instead of following it into a folder we do not own.
+
+    Raises OSError when it cannot delete, unlike `delete_folder`, which only warns.
+    """
+    try:
+        mode = path.lstat().st_mode
+    except (FileNotFoundError, NotADirectoryError):
+        return
+    if stat.S_ISDIR(mode):
+        make_folders_writable(path)
+        shutil.rmtree(os.fspath(path))
+    else:
+        path.unlink()
+
+
+def make_folders_writable(root: Path) -> None:
+    """Let ``rmtree`` delete what read-only folders under ``root`` hold.
+
+    Best effort: a folder it cannot change is left as it is.
+    """
+    if root.is_symlink():
+        return
+    _make_writable(root)
+    for folder, subfolders, _ in os.walk(root):
+        for name in subfolders:
+            subfolder = os.path.join(folder, name)
+            # chmod follows links, so a linked folder is skipped to keep the change
+            # inside `root` (CWE-59). Each one is changed before os.walk lists it.
+            if not os.path.islink(subfolder):
+                _make_writable(subfolder)
+
+
+def _make_writable(folder: str | Path) -> None:
+    with contextlib.suppress(OSError):
+        os.chmod(folder, stat.S_IRWXU)
+
+
+def is_real_dir(path: Path) -> bool:
+    """Whether `path` is a folder and not a link: a committed link can lead anywhere.
+
+    Uses `os.path`: before Python 3.14, `Path.is_dir` and `Path.is_symlink` raise
+    PermissionError under a folder that cannot be searched.
+    """
+    return not os.path.islink(path) and os.path.isdir(path)
+
+
+def first_copy_error(error: OSError) -> str:
+    """The reason of the first failed file, instead of copytree's list of all of them."""
+    # copytree collects every failed file into one shutil.Error holding a list of
+    # (source, target, reason) tuples.
+    if isinstance(error, shutil.Error) and error.args:
+        failures = error.args[0]
+        if (
+            isinstance(failures, list)
+            and failures
+            and isinstance(failures[0], tuple)
+            and len(failures[0]) == 3
+        ):
+            return str(failures[0][2])
+    return str(error)

{google_agents_cli-1.8.0 → google_agents_cli-1.10.0}/src/google/agents/cli/_project.py

@@ -32,6 +32,17 @@ import yaml
 # ADK; new projects get the value from their template.
 DEFAULT_FRAMEWORK = "google-adk"
 
+# Values of create_params.agent_runtime.identity_default.
+AGENT_IDENTITY = "agent_identity"
+SERVICE_ACCOUNT = "service_account"
+AGENT_RUNTIME_IDENTITY_DEFAULTS = (AGENT_IDENTITY, SERVICE_ACCOUNT)
+
+# create_params the manifest keeps in a per-target section, as flat key ->
+# (section, key in the section). The flat key is the ProjectConfig field.
+NESTED_CREATE_PARAMS = {
+    "agent_runtime_identity_default": ("agent_runtime", "identity_default"),
+}
+
 
 @dataclass
 class ProjectConfig:
@@ -50,6 +61,7 @@ class ProjectConfig:
     cicd_runner: str = "skip"
     agent_gateway: bool = False
     agent_guidance_filename: str = "GEMINI.md"
+    agent_runtime_identity_default: str = SERVICE_ACCOUNT
     # The ADK name of the root agent. Empty means "derive it from the project
     # name"; see resolve_root_agent_name.
     root_agent_name: str = ""
@@ -64,6 +76,7 @@ class ProjectConfig:
             "agent_gateway": self.agent_gateway,
             "agent_guidance_filename": self.agent_guidance_filename,
             "root_agent_name": self.root_agent_name,
+            "agent_runtime_identity_default": self.agent_runtime_identity_default,
         }
 
     @classmethod
@@ -105,6 +118,24 @@ class ProjectConfig:
         cfg.agent_gateway = create_params.get("agent_gateway", cfg.agent_gateway)
         cfg.root_agent_name = create_params.get("root_agent_name") or ""
 
+        for flat_key, (section, key) in NESTED_CREATE_PARAMS.items():
+            values = create_params.get(section)
+            if values is None:
+                continue
+            if not isinstance(values, Mapping):
+                raise click.ClickException(
+                    f"malformed create_params.{section} in {filename}"
+                )
+            if key in values:
+                setattr(cfg, flat_key, values[key])
+
+        if cfg.agent_runtime_identity_default not in AGENT_RUNTIME_IDENTITY_DEFAULTS:
+            raise click.ClickException(
+                f"invalid create_params.agent_runtime.identity_default in {filename}: "
+                f"'{cfg.agent_runtime_identity_default}' is not one of "
+                f"{', '.join(AGENT_RUNTIME_IDENTITY_DEFAULTS)}"
+            )
+
         return cfg
 
 
@@ -182,7 +213,7 @@ def read_project_config(project_dir: str | None = None) -> ProjectConfig:
         return ProjectConfig()
 
 
-def _parse_version(v: str) -> tuple[int, ...]:
+def parse_version(v: str) -> tuple[int, ...]:
     """Parse a dotted numeric version into a comparable tuple.
 
     Raises ``ValueError`` on non-numeric components (e.g. a ``0.0.0-dev``
@@ -201,7 +232,7 @@ def scaffold_older_than(cfg: ProjectConfig, version: str) -> bool:
     if not cfg.acli_version:
         return False
     try:
-        return _parse_version(cfg.acli_version) < _parse_version(version)
+        return parse_version(cfg.acli_version) < parse_version(version)
     except ValueError:
         return False
 
@@ -220,8 +251,8 @@ def check_cli_version(cfg: ProjectConfig) -> None:
     from google.agents.cli import __version__
 
     try:
-        project_ver = _parse_version(acli_version)
-        cli_ver = _parse_version(__version__)
+        project_ver = parse_version(acli_version)
+        cli_ver = parse_version(__version__)
     except ValueError:
         return
 

{google_agents_cli-1.8.0 → google_agents_cli-1.10.0}/src/google/agents/cli/_remote.py

@@ -153,7 +153,7 @@ def build_remote_headers(
     Auto-detects Google Cloud credentials unless the caller supplies
     an ``Authorization`` header via ``--header``.
 
-    Uses an **access token** for Vertex AI / Agent Runtime URLs and an
+    Uses an **access token** for Gemini platform / Agent Runtime URLs and an
     **identity token** (with the service URL as audience) for everything
     else (Cloud Run, GKE, etc.).
     """

{google_agents_cli-1.8.0 → google_agents_cli-1.10.0}/src/google/agents/cli/_runner.py

@@ -14,6 +14,7 @@
 
 """Subprocess helpers for agents CLI."""
 
+import contextlib
 import io
 import os
 import shlex
@@ -222,6 +223,30 @@ def run_extension_command(
     return result.returncode
 
 
+@contextlib.contextmanager
+def _wrap_launch_errors(executable: str | None, args: list[str]):
+    """Turn a resolved tool's launch-time OSError into a ToolNotExecutableError.
+
+    On Windows, shutil.which doesn't check ACLs or security policies, so a
+    blocked tool resolves fine and only fails at launch, even with check=False.
+    Only ERROR_ACCESS_DENIED maps to PermissionError; policy blocks (e.g.
+    WinError 4551 from Application Control) surface as a plain OSError.
+    FileNotFoundError and unresolved executables (``executable is None``) keep
+    the raw error so callers' own handling still applies.
+    """
+    try:
+        yield
+    except FileNotFoundError:
+        raise
+    except (PermissionError, OSError) as e:
+        if executable is None:
+            raise
+        msg = f"'{executable}' was found at '{args[0]}' but could not be executed: {e}"
+        if _tools.is_windows():
+            msg += "\n  It may be blocked by a security policy (e.g. AppLocker, WDAC, Defender)."
+        raise _tools.ToolNotExecutableError(msg) from e
+
+
 def run_resolved(
     args: list[str], *, resolve_executable: bool = True, **kwargs
 ) -> subprocess.CompletedProcess:
@@ -235,6 +260,8 @@ def run_resolved(
 
     Raises:
         ToolNotFoundError: If resolve_executable is True and the tool cannot be found.
+        ToolNotExecutableError: If resolve_executable is True and the OS refuses
+            to execute the resolved tool.
 
     Returns:
         CompletedProcess instance.
@@ -242,13 +269,15 @@ def run_resolved(
     if isinstance(args, str):
         raise ValueError("args must be a list of strings, not a single string.")
 
+    executable = None
     if resolve_executable and args:
         executable = args[0]
         # Create a shallow copy to avoid modifying the original list passed by reference
         args = args.copy()
         args[0] = _tools.require_tool(executable)
 
-    return subprocess.run(args, **kwargs)
+    with _wrap_launch_errors(executable, args):
+        return subprocess.run(args, **kwargs)
 
 
 def popen_resolved(
@@ -264,6 +293,8 @@ def popen_resolved(
 
     Raises:
         ToolNotFoundError: If resolve_executable is True and the tool cannot be found.
+        ToolNotExecutableError: If resolve_executable is True and the OS refuses
+            to execute the resolved tool.
 
     Returns:
         Popen instance.
@@ -271,13 +302,15 @@ def popen_resolved(
     if isinstance(args, str):
         raise ValueError("args must be a list of strings, not a single string.")
 
+    executable = None
     if resolve_executable and args:
         executable = args[0]
         # Create a shallow copy to avoid modifying the original list passed by reference
         args = args.copy()
         args[0] = _tools.require_tool(executable)
 
-    return subprocess.Popen(args, **kwargs)
+    with _wrap_launch_errors(executable, args):
+        return subprocess.Popen(args, **kwargs)
 
 
 def popen_resolved_detached(
@@ -298,6 +331,8 @@ def popen_resolved_detached(
 
     Raises:
         ToolNotFoundError: If resolve_executable is True and the tool cannot be found.
+        ToolNotExecutableError: If resolve_executable is True and the OS refuses
+            to execute the resolved tool.
 
     Returns:
         Popen instance.