The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.pyindex 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 theprofile'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 = commandif 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_clireturn 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.pyindex 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__.pyindex 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.pyindex 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 orderprocess_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.pynew file mode 100644index 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 writablediff --git a/tests/tools/test_delegate_external_provider.py b/tests/tools/test_delegate_external_provider.pyindex 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 osimport sysfrom 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.pyindex 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.pyindex 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 secretdiff --git a/website/docs/developer-guide/model-provider-plugin.md b/website/docs/developer-guide/model-provider-plugin.mdindex 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.