agentshim 0.15.7__tar.gz → 0.16.0__tar.gz

{agentshim-0.15.7 → agentshim-0.16.0}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.16.0 (2026-10-14)
+
+### Added
+
+- `plan_auth(profile, AuthPolicy, env=, home=)` chooses the one credential a CLI logs in
+  with and returns an `AuthPlan`: the exact variables and files to hand it, and the names
+  of the credentials it withheld. `AuthPolicy` names the allowed `CredentialKind`s
+  (`API_KEY`, `SUBSCRIPTION`) and an optional endpoint; with no endpoint, a base URL in
+  the environment is withheld. `AuthUnavailableError` names what is missing.
+- `ProviderProfile.credential_sources` (`EnvCredential`, `FileCredential`, in the CLI's
+  precedence order) and `ProviderProfile.endpoint` (`EndpointSpec`) declare each CLI's
+  credentials as data. opencode declares none, so no policy can be enforced for it.
+- `ProviderStatus.credential`: the kind of credential the CLI reports it is using (Claude
+  from `claude auth status`'s `authMethod`, Codex from `codex login status`), or `None`.
+
+### Changed
+
+- `auth_env_vars` lists `CLAUDE_CODE_OAUTH_TOKEN` (claude) and `CODEX_API_KEY` (codex),
+  which the CLIs and their readiness probes already honoured.
+
 ## 0.15.7 (2026-10-09)
 
 ### Added

{agentshim-0.15.7 → agentshim-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.15.7
+Version: 0.16.0
 Summary: Provider-agnostic coding-agent CLI shims
 License-Expression: MIT
 License-File: LICENSE

{agentshim-0.15.7 → agentshim-0.16.0}/agentshim/__init__.py

@@ -15,7 +15,10 @@ from .core import (
     ApprovalPolicy,
     ArgvContext,
     AssistantText,
+    AuthPlan,
+    AuthPolicy,
     AuthState,
+    AuthUnavailableError,
     Checkpoint,
     CheckpointStore,
     CliCheckError,
@@ -32,8 +35,13 @@ from .core import (
     ContinuityError,
     Conversation,
     ConversationSpec,
+    CredentialKind,
+    CredentialSource,
+    EndpointSpec,
+    EnvCredential,
     EventHandlerBase,
     FailureKind,
+    FileCredential,
     FlagsInstallation,
     HttpMcpServer,
     IdAllocator,
@@ -86,6 +94,7 @@ from .core import (
     SkillSignal,
     SkillSummary,
     SkillTracker,
+    StagedCredentialFile,
     Stderr,
     StdioMcpServer,
     SteerableConversation,
@@ -120,6 +129,7 @@ from .core import (
     normalize,
     normalized_usage,
     parse_json_object,
+    plan_auth,
     prepare_config_home,
     price_for,
 )
@@ -156,7 +166,7 @@ from .providers.opencode import OpencodeProvider
 from .runtime import Agent
 from .session import Session, Turn, TurnTicket, map_mcp_servers
 
-__version__ = "0.15.7"
+__version__ = "0.16.0"
 
 __all__ = [
     "Agent",
@@ -168,7 +178,10 @@ __all__ = [
     "ApprovalPolicy",
     "ArgvContext",
     "AssistantText",
+    "AuthPlan",
+    "AuthPolicy",
     "AuthState",
+    "AuthUnavailableError",
     "CallbackCommandStreamSink",
     "Checkpoint",
     "CheckpointStore",
@@ -200,9 +213,14 @@ __all__ = [
     "Conversation",
     "ConversationSpec",
     "CopilotProvider",
+    "CredentialKind",
+    "CredentialSource",
     "DockerExecConfinement",
+    "EndpointSpec",
+    "EnvCredential",
     "EventHandlerBase",
     "FailureKind",
+    "FileCredential",
     "FlagsInstallation",
     "GeminiProvider",
     "HostCommandExecutor",
@@ -267,6 +285,7 @@ __all__ = [
     "SkillTracker",
     "SkillsDiscovered",
     "SpawnRequest",
+    "StagedCredentialFile",
     "Stderr",
     "StderrLine",
     "StdioMcpServer",
@@ -310,6 +329,7 @@ __all__ = [
     "normalize",
     "normalized_usage",
     "parse_json_object",
+    "plan_auth",
     "prepare_config_home",
     "price_for",
     "probe_provider",

{agentshim-0.15.7 → agentshim-0.16.0}/agentshim/core/__init__.py

@@ -7,6 +7,18 @@ this package may not do.
 
 from __future__ import annotations
 
+from .auth import (
+    AuthPlan,
+    AuthPolicy,
+    AuthUnavailableError,
+    CredentialKind,
+    CredentialSource,
+    EndpointSpec,
+    EnvCredential,
+    FileCredential,
+    StagedCredentialFile,
+    plan_auth,
+)
 from .checkpoints import Checkpoint, CheckpointStore, InMemoryCheckpointStore
 from .clock import Clock, StopSignal, SystemClock
 from .conversation import (
@@ -116,7 +128,10 @@ __all__ = [
     "ApprovalPolicy",
     "ArgvContext",
     "AssistantText",
+    "AuthPlan",
+    "AuthPolicy",
     "AuthState",
+    "AuthUnavailableError",
     "Checkpoint",
     "CheckpointStore",
     "CliCheckError",
@@ -133,8 +148,13 @@ __all__ = [
     "ContinuityError",
     "Conversation",
     "ConversationSpec",
+    "CredentialKind",
+    "CredentialSource",
+    "EndpointSpec",
+    "EnvCredential",
     "EventHandlerBase",
     "FailureKind",
+    "FileCredential",
     "FlagsInstallation",
     "HttpMcpServer",
     "IdAllocator",
@@ -187,6 +207,7 @@ __all__ = [
     "SkillSummary",
     "SkillTracker",
     "SkillsDiscovered",
+    "StagedCredentialFile",
     "Stderr",
     "StdioMcpServer",
     "SteerConsumed",
@@ -221,6 +242,7 @@ __all__ = [
     "normalize",
     "normalized_usage",
     "parse_json_object",
+    "plan_auth",
     "prepare_config_home",
     "price_for",
 ]

agentshim-0.16.0/agentshim/core/auth.py

@@ -0,0 +1,335 @@
+"""Credential policy: which credential a CLI may log in with, and what to hand it.
+
+A CLI can log in several ways, and it picks one by its own precedence rules
+when more than one is present: a pay-per-token key in the environment, a
+subscription login in a file under its state root, a token that a proxy
+issued. A caller that must control which one is used (bill an API key, never
+the operator's subscription) cannot do it by setting one variable: whatever
+else the CLI can see may win. It has to hand the CLI exactly one credential
+and nothing else.
+
+Each provider declares its credentials as data (``ProviderProfile.
+credential_sources``, in the CLI's own precedence order, and
+``ProviderProfile.endpoint``). ``plan_auth`` turns that, a caller's
+``AuthPolicy`` and the host's environment and home into an ``AuthPlan``: the
+exact environment variables and files to deliver. The caller delivers the
+plan and nothing more of the provider's ``auth_env_vars`` or ``auth_files``;
+the readiness probe then reports which kind of credential the CLI says it is
+using (``ProviderStatus.credential``), so the caller can confirm it.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any, cast
+from urllib.parse import urlsplit
+
+from .errors import AgentShimError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+    from pathlib import Path
+
+    from .profile import ProviderProfile
+
+
+class CredentialKind(str, Enum):
+    """What a credential bills and how it lives.
+
+    ``API_KEY`` is a static secret read from the environment or a key file: a
+    vendor API key, or a token a proxy or gateway issued. ``SUBSCRIPTION`` is a
+    personal or team plan login (Claude.ai, ChatGPT, a Google or GitHub
+    account), usually an OAuth token the CLI refreshes.
+    """
+
+    API_KEY = "api_key"
+    SUBSCRIPTION = "subscription"
+
+
+@dataclass(frozen=True)
+class EnvCredential:
+    """A credential the CLI reads from one environment variable."""
+
+    name: str
+    kind: CredentialKind
+
+
+@dataclass(frozen=True)
+class FileCredential:
+    """A credential the CLI reads from a home-relative file.
+
+    The file's kind is either fixed (``kind``) or read from its contents
+    (``classify``, which returns ``None`` for contents it does not recognise);
+    exactly one is set. The path is also one of the profile's
+    ``credential_files``.
+    """
+
+    path: str
+    kind: CredentialKind | None = None
+    classify: Callable[[bytes], CredentialKind | None] | None = field(default=None, compare=False)
+
+    def __post_init__(self) -> None:
+        """Require exactly one of ``kind`` and ``classify``."""
+        if (self.kind is None) == (self.classify is None):
+            msg = f"FileCredential {self.path!r} needs exactly one of kind and classify"
+            raise ValueError(msg)
+
+    def kind_of(self, contents: bytes) -> CredentialKind | None:
+        """The kind of credential *contents* hold, or ``None`` if unrecognised."""
+        if self.kind is not None:
+            return self.kind
+        assert self.classify is not None  # noqa: S101 - __post_init__ guarantees it
+        return self.classify(contents)
+
+
+CredentialSource = EnvCredential | FileCredential
+
+
+@dataclass(frozen=True)
+class EndpointSpec:
+    """How a CLI is pointed at an API endpoint other than its vendor's.
+
+    ``base_url_env`` takes the endpoint URL. ``companion_env`` are variables
+    that only make sense with a custom endpoint (extra headers a gateway
+    needs); they are forwarded from the host only when the policy names an
+    endpoint. ``credentials`` are the kinds the CLI sends to a custom endpoint.
+    """
+
+    base_url_env: str
+    companion_env: tuple[str, ...] = ()
+    credentials: frozenset[CredentialKind] = frozenset({CredentialKind.API_KEY})
+
+
+@dataclass(frozen=True)
+class AuthPolicy:
+    """Which credentials a caller allows, and the endpoint to use.
+
+    ``endpoint`` is ``None`` for the vendor's own endpoint: a base URL left in
+    the host environment is then withheld, not forwarded. A URL sends every
+    request there.
+    """
+
+    credentials: frozenset[CredentialKind]
+    endpoint: str | None = None
+
+    def __post_init__(self) -> None:
+        """Reject an empty credential set and an endpoint that is not an http(s) URL."""
+        if not self.credentials:
+            msg = "AuthPolicy.credentials must allow at least one CredentialKind"
+            raise ValueError(msg)
+        if self.endpoint is not None:
+            parts = urlsplit(self.endpoint)
+            if parts.scheme not in {"http", "https"} or not parts.hostname:
+                msg = (
+                    f"AuthPolicy.endpoint must be an http(s) URL with a host, got {self.endpoint!r}"
+                )
+                raise ValueError(msg)
+
+
+@dataclass(frozen=True)
+class StagedCredentialFile:
+    """A host credential file the CLI must see at ``home_path`` under its home.
+
+    ``refreshable`` files hold a login the CLI rewrites when it refreshes the
+    token; share those writable so the refreshed token reaches the host.
+    """
+
+    host_path: Path
+    home_path: str
+    refreshable: bool
+
+
+@dataclass(frozen=True)
+class AuthPlan:
+    """Exactly what to hand a CLI so it logs in with one allowed credential.
+
+    ``env`` and ``files`` are the whole delivery: a caller that also forwards
+    any other of the profile's ``auth_env_vars`` or ``auth_files`` (settings
+    files included, which can carry credentials of their own) defeats the
+    plan. ``source`` names the chosen credential (a variable name or a
+    home-relative path); ``withheld`` names, never values, the credentials and
+    endpoint settings present on the host that the plan leaves out, for a log.
+    """
+
+    provider: str
+    credential: CredentialKind
+    source: str
+    endpoint: str | None
+    env: Mapping[str, str]
+    files: tuple[StagedCredentialFile, ...]
+    withheld: tuple[str, ...]
+
+
+class AuthUnavailableError(AgentShimError):
+    """No credential the policy allows is present, or the policy cannot be met.
+
+    The message names what each allowed kind would need, and never a value.
+    """
+
+
+def plan_auth(
+    profile: ProviderProfile,
+    policy: AuthPolicy,
+    *,
+    env: Mapping[str, str],
+    home: Path,
+) -> AuthPlan:
+    """Choose the credential *profile*'s CLI will log in with under *policy*.
+
+    Walks the profile's ``credential_sources`` in the CLI's precedence order
+    and takes the first one present on the host (a non-blank variable in
+    *env*, or an existing file under *home* whose contents classify) whose kind
+    the policy allows. Only that credential is delivered, so the CLI cannot
+    prefer another.
+
+    Raises:
+        AuthUnavailableError: the profile declares no credential sources, the
+            policy names an endpoint the CLI cannot take or that accepts none
+            of the allowed kinds, or no allowed credential is present.
+    """
+    allowed = _allowed_kinds(profile, policy)
+    chosen, kind, present = _choose(profile, allowed, env, home)
+    delivered_env: dict[str, str] = {}
+    files: tuple[StagedCredentialFile, ...] = ()
+    if isinstance(chosen, EnvCredential):
+        delivered_env[chosen.name] = env[chosen.name]
+    else:
+        refreshable = kind is CredentialKind.SUBSCRIPTION
+        files = (StagedCredentialFile(home / chosen.path, chosen.path, refreshable),)
+    if policy.endpoint is not None and profile.endpoint is not None:
+        delivered_env[profile.endpoint.base_url_env] = policy.endpoint
+        delivered_env.update(
+            {name: env[name] for name in profile.endpoint.companion_env if _set(env, name)}
+        )
+
+    delivered = set(delivered_env) | {staged.home_path for staged in files}
+    on_host = {name for name in _host_auth_names(profile) if _set(env, name)}
+    on_host |= {path for path in profile.auth_files if (home / path).is_file()}
+    on_host |= set(present)
+    return AuthPlan(
+        provider=profile.name,
+        credential=kind,
+        source=_name(chosen),
+        endpoint=policy.endpoint,
+        env=MappingProxyType(delivered_env),
+        files=files,
+        withheld=tuple(sorted(on_host - delivered)),
+    )
+
+
+def classify_json_field(
+    key: str, kinds: Mapping[str, CredentialKind]
+) -> Callable[[bytes], CredentialKind | None]:
+    """A ``FileCredential.classify`` that maps a top-level JSON string field to a kind.
+
+    Contents that are not a JSON object, lack *key*, or hold a value not in
+    *kinds* classify as ``None``.
+    """
+
+    def classify(contents: bytes) -> CredentialKind | None:
+        try:
+            data: Any = json.loads(contents)
+        except ValueError:
+            return None
+        if not isinstance(data, dict):
+            return None
+        value = cast("dict[str, Any]", data).get(key)
+        return kinds.get(value) if isinstance(value, str) else None
+
+    return classify
+
+
+def _allowed_kinds(profile: ProviderProfile, policy: AuthPolicy) -> frozenset[CredentialKind]:
+    """The kinds *policy* allows that *profile*'s CLI can use with the policy's endpoint."""
+    if not profile.credential_sources:
+        msg = (
+            f"{profile.name} declares no credential sources agentshim can classify, "
+            "so no credential policy can be enforced for it"
+        )
+        raise AuthUnavailableError(msg)
+    if policy.endpoint is None:
+        return policy.credentials
+    if profile.endpoint is None:
+        msg = f"{profile.name} cannot be pointed at another endpoint ({policy.endpoint})"
+        raise AuthUnavailableError(msg)
+    allowed = policy.credentials & profile.endpoint.credentials
+    if not allowed:
+        msg = (
+            f"{profile.name} sends only {_kinds(profile.endpoint.credentials)} credentials "
+            f"to a custom endpoint, and the policy allows {_kinds(policy.credentials)}"
+        )
+        raise AuthUnavailableError(msg)
+    return allowed
+
+
+def _choose(
+    profile: ProviderProfile,
+    allowed: frozenset[CredentialKind],
+    env: Mapping[str, str],
+    home: Path,
+) -> tuple[CredentialSource, CredentialKind, list[str]]:
+    """The first present allowed source, its kind, and every present source's name."""
+    chosen: tuple[CredentialSource, CredentialKind] | None = None
+    present: list[str] = []
+    for source in profile.credential_sources:
+        kind = _present_kind(source, env, home)
+        if kind is None:
+            continue
+        present.append(_name(source))
+        if chosen is None and kind in allowed:
+            chosen = (source, kind)
+    if chosen is None:
+        raise AuthUnavailableError(_unavailable(profile, allowed, present))
+    return chosen[0], chosen[1], present
+
+
+def _present_kind(
+    source: CredentialSource, env: Mapping[str, str], home: Path
+) -> CredentialKind | None:
+    if isinstance(source, EnvCredential):
+        return source.kind if _set(env, source.name) else None
+    path = home / source.path
+    try:
+        contents = path.read_bytes()
+    except OSError:
+        return None
+    return source.kind_of(contents)
+
+
+def _set(env: Mapping[str, str], name: str) -> bool:
+    value = env.get(name)
+    return bool(value and value.strip())
+
+
+def _name(source: CredentialSource) -> str:
+    return source.name if isinstance(source, EnvCredential) else source.path
+
+
+def _host_auth_names(profile: ProviderProfile) -> set[str]:
+    names = set(profile.auth_env_vars)
+    if profile.endpoint is not None:
+        names.add(profile.endpoint.base_url_env)
+        names.update(profile.endpoint.companion_env)
+    return names
+
+
+def _kinds(kinds: frozenset[CredentialKind]) -> str:
+    return ", ".join(sorted(kind.value for kind in kinds))
+
+
+def _unavailable(
+    profile: ProviderProfile, allowed: frozenset[CredentialKind], present: list[str]
+) -> str:
+    wanted = [
+        _name(source)
+        for source in profile.credential_sources
+        if source.kind is None or source.kind in allowed
+    ]
+    found = f"; present but not allowed: {', '.join(present)}" if present else ""
+    return (
+        f"no {_kinds(allowed)} credential for {profile.name} is available: "
+        f"provide one of {', '.join(wanted)}{found}"
+    )

{agentshim-0.15.7 → agentshim-0.16.0}/agentshim/core/profile.py

@@ -16,6 +16,8 @@ from .permissions import NativeMode
 if TYPE_CHECKING:
     from collections.abc import Mapping
 
+    from .auth import CredentialSource, EndpointSpec
+
 
 class McpMechanism(Enum):
     """How a provider is told about MCP servers."""
@@ -220,3 +222,12 @@ class ProviderProfile:
     #: turn runs. A provider that does not (every one-shot transport) rejects
     #: it with ``ProviderCapabilityError`` instead of delaying the message.
     supports_steer: bool = False
+    #: The credentials the CLI can log in with, in the CLI's own precedence
+    #: order (0.16.0+). ``plan_auth`` walks them to choose the one credential
+    #: a caller hands the CLI. Every variable is in ``auth_env_vars`` and every
+    #: file in ``credential_files``. Empty means the CLI's credentials cannot
+    #: be classified, so no credential policy can be enforced for it.
+    credential_sources: tuple[CredentialSource, ...] = ()
+    #: How the CLI is pointed at another API endpoint, or ``None`` if it
+    #: cannot be (0.16.0+).
+    endpoint: EndpointSpec | None = None

{agentshim-0.15.7 → agentshim-0.16.0}/agentshim/core/status.py

@@ -16,6 +16,8 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
 
+    from .auth import CredentialKind
+
 
 class AuthState(str, Enum):
     """Whether the provider CLI is authenticated, as far as its own tooling can say.
@@ -45,6 +47,9 @@ class ProviderStatus:
     version: str | None
     auth: AuthState
     auth_detail: str
+    #: The kind of credential the CLI says it is logged in with (0.16.0+), or
+    #: ``None`` when it did not say or could not be read unambiguously.
+    credential: CredentialKind | None = None
 
 
 @dataclass(frozen=True)
@@ -67,6 +72,7 @@ class AuthCheck:
 
     state: AuthState
     detail: str
+    credential: CredentialKind | None = None
 
 
 @dataclass(frozen=True)

{agentshim-0.15.7 → agentshim-0.16.0}/agentshim/probe.py

@@ -101,6 +101,7 @@ def probe_on(
         version=version,
         auth=check.state,
         auth_detail=check.detail,
+        credential=check.credential,
     )
 
 

{agentshim-0.15.7 → agentshim-0.16.0}/agentshim/providers/claude/probe.py

@@ -4,6 +4,12 @@ The command prints a JSON object (``loggedIn``, ``authMethod``, ...) and exits
 1 when logged out. It reads local credentials and the environment
 (``ANTHROPIC_API_KEY``, ``CLAUDE_CODE_OAUTH_TOKEN``) only; it makes no model
 request.
+
+``authMethod`` names the credential in use (Claude Code 2.1): ``claude.ai``
+for the stored subscription login, ``api_key`` for ``ANTHROPIC_API_KEY``, and
+``oauth_token`` for both ``ANTHROPIC_AUTH_TOKEN`` (a static token, often a
+gateway's) and ``CLAUDE_CODE_OAUTH_TOKEN`` (a subscription token). Only the
+environment the command ran with tells those last two apart.
 """
 
 from __future__ import annotations
@@ -11,6 +17,7 @@ from __future__ import annotations
 import json
 from typing import TYPE_CHECKING, Any, cast
 
+from agentshim.core.auth import CredentialKind
 from agentshim.core.status import AuthCheck, AuthProbe, AuthState, ProbeOutput, ProbeSpec
 
 if TYPE_CHECKING:
@@ -21,7 +28,6 @@ LOGIN_HINT = "run `claude auth login` or set ANTHROPIC_API_KEY"
 
 def read_auth(output: ProbeOutput, env: Mapping[str, str]) -> AuthCheck:
     """Read ``claude auth status``'s JSON."""
-    del env
     try:
         data: Any = json.loads(output.stdout)
     except ValueError:
@@ -33,12 +39,25 @@ def read_auth(output: ProbeOutput, env: Mapping[str, str]) -> AuthCheck:
     if logged_in is True:
         method = status.get("authMethod")
         how = f" ({method})" if isinstance(method, str) and method != "none" else ""
-        return AuthCheck(AuthState.KNOWN_OK, f"logged in{how}")
+        return AuthCheck(AuthState.KNOWN_OK, f"logged in{how}", _credential(method, env))
     if logged_in is False:
         return AuthCheck(AuthState.FAILED, f"claude is not logged in; {LOGIN_HINT}")
     return AuthCheck(AuthState.UNKNOWN, _unrecognised(output))
 
 
+def _credential(method: object, env: Mapping[str, str]) -> CredentialKind | None:
+    if method == "claude.ai":
+        return CredentialKind.SUBSCRIPTION
+    if method == "api_key":
+        return CredentialKind.API_KEY
+    if method == "oauth_token":
+        bearer = bool(env.get("ANTHROPIC_AUTH_TOKEN", "").strip())
+        subscription = bool(env.get("CLAUDE_CODE_OAUTH_TOKEN", "").strip())
+        if bearer != subscription:
+            return CredentialKind.API_KEY if bearer else CredentialKind.SUBSCRIPTION
+    return None
+
+
 def _unrecognised(output: ProbeOutput) -> str:
     return f"unrecognised `claude auth status` output (exit {output.returncode})"
 

{agentshim-0.15.7 → agentshim-0.16.0}/agentshim/providers/claude/provider.py

@@ -5,6 +5,12 @@ from __future__ import annotations
 import json
 from typing import TYPE_CHECKING, Any
 
+from agentshim.core.auth import (
+    CredentialKind,
+    EndpointSpec,
+    EnvCredential,
+    FileCredential,
+)
 from agentshim.core.errors import FailureKind, ProviderCapabilityError, SessionResumeError
 from agentshim.core.mcp import HttpMcpServer, NoopInstallation, StdioMcpServer, install_config_file
 from agentshim.core.profile import (
@@ -75,6 +81,7 @@ PROFILE = ProviderProfile(
     auth_env_vars=(
         "ANTHROPIC_AUTH_TOKEN",
         "ANTHROPIC_API_KEY",
+        "CLAUDE_CODE_OAUTH_TOKEN",
         "ANTHROPIC_BASE_URL",
         "ANTHROPIC_CUSTOM_HEADERS",
     ),
@@ -103,6 +110,16 @@ PROFILE = ProviderProfile(
         ".claude.json",
     ),
     credential_files=(".claude/.credentials.json",),
+    # Precedence as ``claude auth status`` reports it: a bearer token beats an
+    # API key, which beats a subscription token (``claude setup-token``),
+    # which beats the stored Claude.ai login.
+    credential_sources=(
+        EnvCredential("ANTHROPIC_AUTH_TOKEN", CredentialKind.API_KEY),
+        EnvCredential("ANTHROPIC_API_KEY", CredentialKind.API_KEY),
+        EnvCredential("CLAUDE_CODE_OAUTH_TOKEN", CredentialKind.SUBSCRIPTION),
+        FileCredential(".claude/.credentials.json", kind=CredentialKind.SUBSCRIPTION),
+    ),
+    endpoint=EndpointSpec("ANTHROPIC_BASE_URL", companion_env=("ANTHROPIC_CUSTOM_HEADERS",)),
     mcp_config_file=MCP_CONFIG_FILENAME,
 )
 

{agentshim-0.15.7 → agentshim-0.16.0}/agentshim/providers/codex/probe.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from agentshim.core.auth import CredentialKind
 from agentshim.core.status import AuthCheck, AuthProbe, AuthState, ProbeOutput, ProbeSpec
 
 if TYPE_CHECKING:
@@ -22,12 +23,20 @@ LOGIN_HINT = "run `codex login`"
 _API_KEY_ENV = ("CODEX_API_KEY", "OPENAI_API_KEY")
 
 
+def _credential(line: str) -> CredentialKind | None:
+    if line.startswith("Logged in using ChatGPT"):
+        return CredentialKind.SUBSCRIPTION
+    if line.startswith("Logged in using an API key"):
+        return CredentialKind.API_KEY
+    return None
+
+
 def read_auth(output: ProbeOutput, env: Mapping[str, str]) -> AuthCheck:
     """Read ``codex login status``'s text."""
     lines = [line.strip() for line in output.text.splitlines() if line.strip()]
     for line in lines:
         if line.startswith("Logged in"):
-            return AuthCheck(AuthState.KNOWN_OK, line)
+            return AuthCheck(AuthState.KNOWN_OK, line, _credential(line))
     if any(line.startswith("Not logged in") for line in lines):
         if any(env.get(key) for key in _API_KEY_ENV):
             return AuthCheck(

{agentshim-0.15.7 → agentshim-0.16.0}/agentshim/providers/codex/provider.py

@@ -6,6 +6,13 @@ import os
 import re
 from typing import TYPE_CHECKING, Any
 
+from agentshim.core.auth import (
+    CredentialKind,
+    EndpointSpec,
+    EnvCredential,
+    FileCredential,
+    classify_json_field,
+)
 from agentshim.core.errors import ProviderCapabilityError, SessionResumeError
 from agentshim.core.home import state_root
 from agentshim.core.mcp import FlagsInstallation, HttpMcpServer, NoopInstallation
@@ -81,7 +88,7 @@ PROFILE = ProviderProfile(
         "Library/Application Support/com.openai.codex",
         "Library/Caches/codex",
     ),
-    auth_env_vars=("OPENAI_API_KEY", "OPENAI_BASE_URL"),
+    auth_env_vars=("CODEX_API_KEY", "OPENAI_API_KEY", "OPENAI_BASE_URL"),
     skill_dirs=(".agents/skills",),
     # ``exec --json`` lists no skills; a load is inferred from a shell read
     # of a ``SKILL.md`` (``skills.py``).
@@ -102,6 +109,20 @@ PROFILE = ProviderProfile(
     # not needlessly expose it to an agent process.
     auth_files=(".codex/auth.json",),
     credential_files=(".codex/auth.json",),
+    # ``codex exec`` takes either key in place of a stored login. auth.json
+    # records which login it holds (``codex login`` vs ``--with-api-key``).
+    credential_sources=(
+        EnvCredential("CODEX_API_KEY", CredentialKind.API_KEY),
+        EnvCredential("OPENAI_API_KEY", CredentialKind.API_KEY),
+        FileCredential(
+            ".codex/auth.json",
+            classify=classify_json_field(
+                "auth_mode",
+                {"chatgpt": CredentialKind.SUBSCRIPTION, "apikey": CredentialKind.API_KEY},
+            ),
+        ),
+    ),
+    endpoint=EndpointSpec("OPENAI_BASE_URL"),
     # Every turn writes a rollout under sessions/, and `resume` reads it back.
     # The rest of the state directory (worktrees, caches, logs) is not needed
     # to log in or resume.

{agentshim-0.15.7 → agentshim-0.16.0}/agentshim/providers/copilot/provider.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 from typing import TYPE_CHECKING, Any
 
+from agentshim.core.auth import CredentialKind, EnvCredential, FileCredential
 from agentshim.core.errors import ProviderCapabilityError
 from agentshim.core.mcp import FlagsInstallation, HttpMcpServer, NoopInstallation
 from agentshim.core.profile import McpMechanism, OutputSchemaStyle, ProviderProfile
@@ -61,6 +62,13 @@ PROFILE = ProviderProfile(
     # config.json carries the logged-in users and, without a keychain, the
     # tokens; the CLI rewrites it in place on login and refresh.
     credential_files=(".copilot/config.json",),
+    # Every Copilot credential is a GitHub login tied to a Copilot plan.
+    credential_sources=(
+        EnvCredential("COPILOT_GITHUB_TOKEN", CredentialKind.SUBSCRIPTION),
+        EnvCredential("GH_TOKEN", CredentialKind.SUBSCRIPTION),
+        EnvCredential("GITHUB_TOKEN", CredentialKind.SUBSCRIPTION),
+        FileCredential(".copilot/config.json", kind=CredentialKind.SUBSCRIPTION),
+    ),
     # CLI_FLAGS: Copilot takes MCP servers as one --additional-mcp-config
     # flag, never a file.
     mcp_config_file=None,

{agentshim-0.15.7 → agentshim-0.16.0}/agentshim/providers/gemini/provider.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
+from agentshim.core.auth import CredentialKind, EnvCredential, FileCredential
 from agentshim.core.errors import ProviderCapabilityError, SessionResumeError
 from agentshim.core.mcp import (
     HttpMcpServer,
@@ -81,6 +82,11 @@ PROFILE = ProviderProfile(
         ".gemini/.env",
     ),
     credential_files=(".gemini/oauth_creds.json",),
+    credential_sources=(
+        EnvCredential("GEMINI_API_KEY", CredentialKind.API_KEY),
+        EnvCredential("GOOGLE_API_KEY", CredentialKind.API_KEY),
+        FileCredential(".gemini/oauth_creds.json", kind=CredentialKind.SUBSCRIPTION),
+    ),
     mcp_config_file=MCP_CONFIG_FILENAME,
 )
 

{agentshim-0.15.7 → agentshim-0.16.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentshim"
-version = "0.15.7"
+version = "0.16.0"
 description = "Provider-agnostic coding-agent CLI shims"
 readme = "README.md"
 license = "MIT"