Skip to content

The agent that grows with you

refactor(acp): delegation.command and launch-env policy come from external_process profiles

Tekniumcd4433dd0e0a
diff --git a/hermes_cli/auth_external_process.py b/hermes_cli/auth_external_process.py
index 4a47f3681f7..144e604cc37 100644
--- a/hermes_cli/auth_external_process.py
+++ b/hermes_cli/auth_external_process.py
@@ -1,4 +1,4 @@
-"""Executable lookup for ``external_process`` (ACP) providers.
+"""Executable lookup and launch-env policy for ``external_process`` (ACP) providers.
A GUI/service launch (LaunchAgent, Desktop backend, Desktop over SSH) has a bare PATH, so the
profile's command resolves through PATH, then the user-local bin, then Claude Code's install
@@ -19,7 +19,7 @@ def resolve_external_process_command(command: str) -> Optional[str]:
lookup = command
if os.sep in command or (os.altsep and os.altsep in command):
- # An operator-configured relative path (./bin/copilot) means the launch cwd, as it did
+ # An operator-configured relative path (./bin/agent) means the launch cwd, as it did
# under shutil.which; anchor it so the resolver's absolute-only explicit check accepts it.
lookup = os.path.abspath(os.path.expandvars(os.path.expanduser(command)))
found = locate_command(lookup, known_dirs=user_local_bin()).command
@@ -30,3 +30,13 @@ def resolve_external_process_command(command: str) -> Optional[str]:
from agent.anthropic_adapter import find_claude_code_cli
return find_claude_code_cli(command)
+
+
+def external_process_launch_env_names() -> frozenset[str]:
+ """Env names that choose an external-process provider's executable or argv, from every registered
+ profile's ``process_command_env_vars`` and ``process_args_env_var``: executable authority, so the
+ generic env writers (dashboard, MCP/connector installs, ``save_env_value``) must refuse them."""
+ from providers import list_providers
+
+ return frozenset(name for profile in list_providers() if profile.auth_type == "external_process"
+ for name in (*profile.process_command_env_vars, profile.process_args_env_var) if name)
diff --git a/hermes_cli/config.py b/hermes_cli/config.py
index 18d348a668f..6d19dfdbd14 100644
--- a/hermes_cli/config.py
+++ b/hermes_cli/config.py
@@ -124,8 +124,6 @@ _ENV_VAR_NAME_DENYLIST: frozenset[str] = frozenset({
"HERMES_CONFIG_PATH", "HERMES_ENV_PATH",
# MCP catalog trust root; package-manager wrappers may still set it in the process env.
"HERMES_OPTIONAL_MCPS",
- # Local ACP subprocess selection (executable/argv authority).
- "HERMES_COPILOT_ACP_COMMAND", "HERMES_COPILOT_ACP_ARGS",
# Security policy / approval-routing context — set via their dedicated controls only.
"HERMES_YOLO_MODE", "HERMES_ACCEPT_HOOKS", "HERMES_REDACT_SECRETS",
"HERMES_INTERACTIVE", "HERMES_EXEC_ASK", "HERMES_GATEWAY_SESSION",
@@ -145,7 +143,9 @@ def validate_env_var_name_for_write(key: str) -> None:
if not _ENV_VAR_NAME_RE.match(key):
raise ValueError(f"Invalid environment variable name: {key!r}")
policy_name = _env_var_policy_name(key)
- if policy_name in _ENV_VAR_NAME_DENYLIST or policy_name.startswith(_ENV_VAR_NAME_DENY_PREFIXES):
+ from hermes_cli.auth_external_process import external_process_launch_env_names as _launch_env # ACP argv authority
+ if (policy_name in _ENV_VAR_NAME_DENYLIST or policy_name in map(_env_var_policy_name, _launch_env())
+ or policy_name.startswith(_ENV_VAR_NAME_DENY_PREFIXES)):
raise ValueError(
f"Environment variable {key!r} is on the writer denylist. "
"Names that influence subprocess execution (LD_PRELOAD, PYTHONPATH, PATH, EDITOR, ...) "
diff --git a/plugins/model-providers/copilot-acp/__init__.py b/plugins/model-providers/copilot-acp/__init__.py
index 7e26046f86b..0ae2113e030 100644
--- a/plugins/model-providers/copilot-acp/__init__.py
+++ b/plugins/model-providers/copilot-acp/__init__.py
@@ -59,6 +59,8 @@ copilot_acp = CopilotACPProfile(
process_args=("--acp", "--stdio"),
process_command_env_vars=("HERMES_COPILOT_ACP_COMMAND", "COPILOT_CLI_PATH"),
process_args_env_var="HERMES_COPILOT_ACP_ARGS",
+ # A delegation.command no other profile claims has always run through this ACP client.
+ process_command_fallback=True,
)
register_provider(copilot_acp)
diff --git a/providers/base.py b/providers/base.py
index 90f9f8e15a9..37d30d57384 100644
--- a/providers/base.py
+++ b/providers/base.py
@@ -217,11 +217,16 @@ class ProviderProfile:
# resolve_external_process_provider_credentials() reads them instead of
# hardcoding one vendor's binary. Env vars are checked in order and win
# over the static defaults, so an operator can point at a custom build.
- process_command: str = "" # default binary, e.g. "copilot"
- process_args: tuple = () # default argv tail, e.g. ("--acp", "--stdio")
+ process_command: str = "" # default binary, e.g. "kimchi"
+ process_args: tuple = () # default argv tail, e.g. ("--mode", "acp")
process_command_env_vars: tuple = () # env overrides for the binary, in priority order
process_args_env_var: str = "" # env override for argv (shlex-split)
+ # ── L5: external-process (ACP) seams ──
+ # Serves a pinned ``delegation.command`` whose binary no profile's process_command names (a
+ # generic ACP stdio client); the first registered profile setting it wins.
+ process_command_fallback: bool = False
+
# ── Model catalog ─────────────────────────────────────────
# fallback_models: curated list shown in /model picker when live fetch fails.
# Only agentic models that support tool calling should appear here.
diff --git a/tests/hermes_cli/test_external_process_launch_env.py b/tests/hermes_cli/test_external_process_launch_env.py
new file mode 100644
index 00000000000..3d1f755bbb2
--- /dev/null
+++ b/tests/hermes_cli/test_external_process_launch_env.py
@@ -0,0 +1,33 @@
+"""Launch-env policy for external-process (ACP) providers comes from their profiles' ``process_*`` fields."""
+
+import pytest
+
+import providers
+from providers.base import ProviderProfile
+
+
+def vendor_profiles(monkeypatch):
+ profiles = [
+ ProviderProfile(name="vendor-acp", auth_type="external_process", process_command="vendor",
+ process_command_env_vars=("VENDOR_ACP_COMMAND", "VENDOR_CLI_PATH"),
+ process_args_env_var="VENDOR_ACP_ARGS"),
+ ProviderProfile(name="vendor-api", auth_type="api_key", env_vars=("VENDOR_API_KEY",)),
+ ]
+ monkeypatch.setattr(providers, "list_providers", lambda: list(profiles))
+ return profiles
+
+
+def test_launch_env_names_cover_every_external_process_override(vendor_profiles):
+ from hermes_cli.auth_external_process import external_process_launch_env_names
+
+ assert external_process_launch_env_names() == {"VENDOR_ACP_COMMAND", "VENDOR_CLI_PATH", "VENDOR_ACP_ARGS"}
+
+
[email protected]("name", ["VENDOR_ACP_COMMAND", "VENDOR_CLI_PATH", "VENDOR_ACP_ARGS"])
+def test_env_writer_refuses_a_provider_executable_override(vendor_profiles, name):
+ from hermes_cli.config import validate_env_var_name_for_write
+
+ with pytest.raises(ValueError, match="writer denylist"):
+ validate_env_var_name_for_write(name)
+ validate_env_var_name_for_write("VENDOR_API_KEY") # an ordinary provider secret stays writable
diff --git a/tests/tools/test_delegate_external_provider.py b/tests/tools/test_delegate_external_provider.py
index 7d204632e70..358a2d51bb8 100644
--- a/tests/tools/test_delegate_external_provider.py
+++ b/tests/tools/test_delegate_external_provider.py
@@ -1,4 +1,5 @@
"""A selected external-process provider must survive child command resolution."""
+import os
import sys
from types import SimpleNamespace
@@ -22,3 +23,47 @@ def test_pinned_command_retains_selected_external_provider(external):
assert result["provider"] == (profile.name if external else "copilot-acp")
assert result["requested_provider"] == result["provider"]
assert result["acp_command"] == sys.executable
+
+
+def _resolve_pinned(command, provider="api-provider"):
+ parent = SimpleNamespace(model="m", provider=provider, base_url="https://api.example/v1",
+ api_mode="chat_completions", acp_args=[])
+ return _resolve_child_runtime(
+ parent, {}, "key", model=None, override_provider=provider, override_base_url=None, override_api_key=None,
+ override_api_mode=None, override_acp_command=command, override_acp_args=[],
+ )
+
+
+def process_profiles(monkeypatch):
+ """Swap the provider registry the resolver reads for a fixed set of profiles."""
+ import providers
+
+ def install(*profiles):
+ by_name = {p.name: p for p in profiles}
+ monkeypatch.setattr(providers, "get_provider_profile", by_name.get)
+ monkeypatch.setattr(providers, "list_providers", lambda: list(profiles))
+ return install
+
+
+def test_pinned_command_resolves_the_profile_that_launches_that_binary(process_profiles):
+ binary = os.path.basename(sys.executable)
+ process_profiles(
+ ProviderProfile(name="api-provider", auth_type="api_key"),
+ ProviderProfile(name="generic-acp", auth_type="external_process", process_command="agent-cli",
+ process_command_fallback=True),
+ ProviderProfile(name="harness-acp", auth_type="external_process", process_command=binary,
+ api_mode="chat_completions"),
+ )
+ result = _resolve_pinned(sys.executable)
+ assert (result["provider"], result["api_mode"], result["acp_command"]) == (
+ "harness-acp", "chat_completions", sys.executable)
+
+
+def test_pinned_command_without_a_matching_or_fallback_profile_fails_loudly(process_profiles):
+ process_profiles(
+ ProviderProfile(name="api-provider", auth_type="api_key"),
+ ProviderProfile(name="harness-acp", auth_type="external_process", process_command="some-other-cli"),
+ )
+ with pytest.raises(ValueError, match="does not belong to any installed external-process provider"):
+ _resolve_pinned(sys.executable)
diff --git a/tools/delegate_tool_config.py b/tools/delegate_tool_config.py
index d8e4a213e82..f3bc6c3637b 100644
--- a/tools/delegate_tool_config.py
+++ b/tools/delegate_tool_config.py
@@ -327,6 +327,35 @@ def _require_pinned_command(command: Optional[str], message: str) -> None:
if command and not _shutil.which(command):
raise ValueError(message)
+def _process_command_provider(
+ command: str, provider: Optional[str], api_mode: Optional[str],
+) -> tuple[str, Optional[str]]:
+ """(provider, api_mode) that runs a pinned ``delegation.command``: the selected provider when it is
+ already an external-process one; else the external-process profile whose ``process_command`` names the
+ same binary; else the profile flagged ``process_command_fallback``. No candidate fails the spawn."""
+ from providers import get_provider_profile, list_providers
+
+ selected = get_provider_profile(provider or "")
+ if selected is not None and selected.auth_type == "external_process":
+ return provider, api_mode
+ candidates = [p for p in list_providers() if p.auth_type == "external_process"]
+ binary = _command_stem(command)
+ match = next((p for p in candidates if p.process_command and _command_stem(p.process_command) == binary), None)
+ match = match or next((p for p in candidates if p.process_command_fallback), None)
+ if match is None:
+ raise ValueError(
+ f"Pinned delegation command '{command}' does not belong to any installed external-process provider. "
+ "Install the provider plugin for it, or remove delegation.command from config.yaml.")
+ return match.name, match.api_mode or "chat_completions"
+
+
+def _command_stem(command: str) -> str:
+ """Binary name of ``command`` without directory or a Windows launcher suffix (``kimchi.cmd`` -> ``kimchi``)."""
+ name = os.path.basename(command.strip().replace("\\", "/")).lower()
+ stem, ext = os.path.splitext(name)
+ return stem if ext in {".exe", ".cmd", ".bat", ".ps1"} else name
+
+
def _credential_bundle(model, provider, base_url, api_key, api_mode, request_overrides, **extra) -> dict:
"""The child credential dict every branch of ``_resolve_delegation_credentials`` returns."""
return {
@@ -529,7 +558,7 @@ def _resolve_child_runtime(
pinned provider is actually honoured."""
effective_model = model or parent_agent.model
# provider/base_url are one bundle: all from the override, or all from the parent. Per-field fallback built
- # children like an override provider pointed at the PARENT's endpoint (e.g. copilot credentials on the
+ # children like an override provider pointed at the PARENT's endpoint (e.g. one provider's credentials on the
# parent's Codex URL), which 404s on every request and can't be rescued by the fallback chain, whose dedup
# matches provider+model and so skips the entry as a self-loop. _inherit_parent_endpoint recovers the
# parent's live endpoint (with its key), which is meaningless for a different provider.
@@ -571,10 +600,8 @@ def _resolve_child_runtime(
effective_acp_args = list(
override_acp_args if override_acp_args is not None else (getattr(parent_agent, "acp_args", []) or [])
)
- # A pinned provider must use direct API calls; inheriting the parent's ACP
- # transport would bypass the override credentials entirely.
- # Inheriting acp_command unconditionally causes run_agent.py to initialize CopilotACPClient, bypassing
- # override credentials entirely (issue #16816).
+ # A pinned provider must use direct API calls; inheriting the parent's ACP transport would build the
+ # ACP client and bypass the override credentials entirely (issue #16816).
if override_provider and not override_acp_command:
effective_acp_command, effective_acp_args = None, []
# Defensive: validate trusted delegation.command exists on PATH before honoring it. An explicitly pinned
@@ -582,11 +609,8 @@ def _resolve_child_runtime(
# transport would run the child somewhere the user explicitly routed it away from. Normally unreachable
# via delegate_task, which pre-validates the command in _resolve_delegation_credentials.
if override_acp_command:
- from providers import get_provider_profile
- profile = get_provider_profile(effective_provider or "")
- # A generic process command does not imply the legacy ACP protocol.
- if profile is None or profile.auth_type != "external_process":
- effective_provider, effective_api_mode = "copilot-acp", "chat_completions"
+ effective_provider, effective_api_mode = _process_command_provider(
+ override_acp_command, effective_provider, effective_api_mode)
# A named provider identity is endpoint-scoped. Preserve it only when the
# child inherits the exact parent route; an override owns its final identity.
diff --git a/tools/environments/local_env_policy.py b/tools/environments/local_env_policy.py
index 3dfb9988171..a6827380676 100644
--- a/tools/environments/local_env_policy.py
+++ b/tools/environments/local_env_policy.py
@@ -209,7 +209,7 @@ def _is_provider_env_blocklisted(name: str, _registered: frozenset | None = None
# computer-use driver binary, and user-script runners (bang ``!`` commands, quick commands, cron scripts,
# webhook-filter scripts), so those children receive the vars too — matching the approved background/PTY
# scope. Every other surface stays sealed — execute_code scrubbing, :func:`hermes_subprocess_env` (browser /
-# TUI host / copilot-executor spawns), docker children, and ``env_passthrough`` registration (skills/config
+# TUI host / ACP agent spawns), docker children, and ``env_passthrough`` registration (skills/config
# still cannot register these names). The GHSA-rhgp-j443-p4rf seal is preserved because no registration path
# is opened; this is a scrub-path exemption, not an allowlist addition. First-party matches use the merged
# env value directly — they are the process's own env values and are never scope-resolved (a profile secret
diff --git a/website/docs/developer-guide/model-provider-plugin.md b/website/docs/developer-guide/model-provider-plugin.md
index 0d290a90dac..d670dbdb6be 100644
--- a/website/docs/developer-guide/model-provider-plugin.md
+++ b/website/docs/developer-guide/model-provider-plugin.md
@@ -254,10 +254,13 @@ An agent CLI driven over stdio is not an HTTP endpoint. Set `auth_type="external
| Field | Purpose |
|---|---|
-| `process_command` | Default binary, e.g. `"copilot"` |
-| `process_args` | Default argv tail, e.g. `("--acp", "--stdio")` |
+| `process_command` | Default binary, e.g. `"kimchi"`. A pinned `delegation.command` naming the same binary runs on this provider |
+| `process_args` | Default argv tail, e.g. `("--mode", "acp")` |
| `process_command_env_vars` | Env vars that override the binary, checked in order |
| `process_args_env_var` | Env var that overrides argv (shlex-split) |
+| `process_command_fallback` | `True` makes this provider run a pinned `delegation.command` no profile's `process_command` names (default `False`; first registered wins, none = the spawn fails) |
+
+The `process_command_env_vars` and `process_args_env_var` names are executable authority: Hermes' generic env writers (dashboard, MCP and connector installs, `save_env_value`) refuse them, so set them in `.env` or the shell.
The client your `create_client` returns receives `command` and `args` in `client_kwargs`. If it is already complete and async-safe, declare `HERMES_SKIP_TRANSPORT_WRAP = True` / `HERMES_SKIP_ASYNC_WRAP = True` as class attributes so the auxiliary client does not re-dispatch it through an HTTP wire adapter.