agentshim 0.18.3__tar.gz → 0.20.0__tar.gz

{agentshim-0.18.3 → agentshim-0.20.0}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.20.0 (2026-10-18)
+
+### Added
+
+- `ClaudeProvider(tools=ClaudeToolPolicy(...))`: run Claude Code with only the built-in tools
+  and allow rules the policy names, under `--permission-mode dontAsk`, instead of the
+  always-on `--dangerously-skip-permissions`. `ClaudeToolPolicy.only(["mcp__rs"])` gives a
+  turn no built-in tools and lets it call only that MCP server; `builtin=()` renders
+  `--tools ""`, and each allow rule is its own `--allowedTools` argument so a scoped rule
+  such as `Bash(git log:*)` arrives whole. A turn with an output schema also allows
+  `StructuredOutput`. Without a policy the argv is unchanged.
+
+### Changed
+
+- Provider integrations are resolved through an extensible `ProviderCatalog`; `CliAgent`,
+  `Agent`, `probe_provider` and the consumer test helpers take `catalog=` (#70).
+
+## 0.19.0 (2026-10-17)
+
+### Added
+
+- `ModelSpec` carries what a model picker needs: `display_name` (`"Opus 5.5"`), `family`
+  (`"Claude"`, `"GPT"`, `"Gemini"`), and a within-family ladder, `tier` (a rank, `1` the
+  smallest) with `tier_name` (`"Opus"`). Haiku < Sonnet < Opus < Fable; Luna < Terra < Sol <
+  Astra. All four fields default to `None`, so a caller-built `ModelSpec` keeps working;
+  every shipped entry has a name and family, and every one but `gpt-5.5` a tier.
+  Read them with `model_spec(provider, model)`. A provider's readable name was already
+  `ProviderProfile.display_name`.
+
 ## 0.18.3 (2026-10-16)
 
 ### Fixed

{agentshim-0.18.3 → agentshim-0.20.0}/PKG-INFO

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

{agentshim-0.18.3 → agentshim-0.20.0}/agentshim/__init__.py

@@ -29,6 +29,7 @@ from .core import (
     CompositeEventHandler,
     ConfigFileInstallation,
     ConfigScope,
+    ConnectionOptions,
     ConsoleEventHandler,
     ContextualStreamParser,
     Continuity,
@@ -56,9 +57,6 @@ from .core import (
     McpScope,
     McpServer,
     McpTransport,
-    ModelPricing,
-    ModelSpec,
-    ModelTable,
     NativeMode,
     NativePermissions,
     NoopInstallation,
@@ -69,7 +67,7 @@ from .core import (
     ParsedTurn,
     ParserContext,
     PolicyConfig,
-    PricingTable,
+    PricingContext,
     ProcessClosedError,
     Provider,
     ProviderCapabilityError,
@@ -126,22 +124,16 @@ from .core import (
     UsageReport,
     compact_json,
     compose_event_handlers,
-    context_window,
-    cost_usd,
-    default_models,
-    default_pricing,
     dialect_problems,
     host_auth_plan,
     install_config_file,
     interactive_env,
     materialize,
-    model_spec,
     normalize,
     normalized_usage,
     parse_json_object,
     plan_auth,
     prepare_config_home,
-    price_for,
 )
 from .execution import (
     CallbackCommandStreamSink,
@@ -164,10 +156,26 @@ from .execution import (
     TransformingExecutor,
     confine,
 )
+from .models import ModelSpec, ModelTable, context_window, default_models, model_spec
 from .oneshot import OneShotTransport
+from .pricing import ModelPricing, PricingTable, cost_usd, default_pricing, price_for
 from .probe import probe_provider
-from .providers import get_provider, provider_names, stream_provider_names
-from .providers.claude import ClaudeHook, ClaudeProvider, ClaudeStreamTransport, SandboxConfig
+from .providers import (
+    DEFAULT_CATALOG,
+    ProviderCatalog,
+    ProviderPlugin,
+    ProviderTestSupport,
+    get_provider,
+    provider_names,
+    stream_provider_names,
+)
+from .providers.claude import (
+    ClaudeHook,
+    ClaudeProvider,
+    ClaudeStreamTransport,
+    ClaudeToolPolicy,
+    SandboxConfig,
+)
 from .providers.codex import CodexProvider, CodexSandboxConfig
 from .providers.codex.app_server import CodexAppServerTransport
 from .providers.copilot import CopilotProvider
@@ -176,9 +184,9 @@ from .providers.opencode import OpencodeProvider
 from .runtime import Agent
 from .session import Session, Turn, TurnTicket, map_mcp_servers
 
-__version__ = "0.18.3"
+__version__ = "0.20.0"
 
-__all__ = [
+__all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "Agent",
     "AgentEvent",
     "AgentEventHandler",
@@ -198,6 +206,7 @@ __all__ = [
     "ClaudeHook",
     "ClaudeProvider",
     "ClaudeStreamTransport",
+    "ClaudeToolPolicy",
     "CliAgent",
     "CliCheckError",
     "CliExitError",
@@ -216,6 +225,7 @@ __all__ = [
     "ConfigFileInstallation",
     "ConfigScope",
     "Confinement",
+    "ConnectionOptions",
     "ConsoleEventHandler",
     "ContextualStreamParser",
     "Continuity",
@@ -225,6 +235,7 @@ __all__ = [
     "CopilotProvider",
     "CredentialKind",
     "CredentialSource",
+    "DEFAULT_CATALOG",
     "DockerExecConfinement",
     "EndpointSpec",
     "EnvCredential",
@@ -264,6 +275,7 @@ __all__ = [
     "ParsedTurn",
     "ParserContext",
     "PolicyConfig",
+    "PricingContext",
     "PricingTable",
     "Process",
     "ProcessClosedError",
@@ -271,9 +283,12 @@ __all__ = [
     "ProcessOutput",
     "Provider",
     "ProviderCapabilityError",
+    "ProviderCatalog",
     "ProviderError",
+    "ProviderPlugin",
     "ProviderProfile",
     "ProviderStatus",
+    "ProviderTestSupport",
     "ProviderUsage",
     "RandomIds",
     "RateLimitStatus",

{agentshim-0.18.3 → agentshim-0.20.0}/agentshim/agent.py

@@ -38,7 +38,7 @@ from agentshim.core.skills import SkillTracker
 from agentshim.core.turn import TurnRequest, TurnResult, coerce_request
 from agentshim.execution.executor import CommandRequest
 from agentshim.execution.host import HostCommandExecutor
-from agentshim.providers import get_provider
+from agentshim.providers import DEFAULT_CATALOG, ProviderCatalog, get_provider
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping, Sequence
@@ -51,14 +51,14 @@ if TYPE_CHECKING:
     from agentshim.execution.executor import CommandExecutor, CommandHandle, CommandResult
 
 
-def _resolve_provider(provider: str | Provider) -> Provider:
+def _resolve_provider(provider: str | Provider, catalog: ProviderCatalog) -> Provider:
     """Resolve a provider name to a provider instance.
 
     This module sits above ``providers`` precisely so the documented
     ``CliAgent("claude")`` spelling can be a plain module-level import.
     """
     if isinstance(provider, str):
-        return get_provider(provider)
+        return get_provider(provider, catalog=catalog)
     return provider
 
 
@@ -82,6 +82,7 @@ class CliAgent:
         event_handlers: Sequence[AgentEventHandler] = (),
         check_timeout: float = 15.0,
         log: Callable[[str], None] | None = None,
+        catalog: ProviderCatalog = DEFAULT_CATALOG,
     ) -> None:
         """Configure a provider CLI and prove it is usable before any turn runs.
 
@@ -104,8 +105,9 @@ class CliAgent:
             check_timeout: Seconds allowed for the one-off health check. It is
                 not a budget for a turn.
             log: Sink for agentshim's own progress lines; dropped by default.
+            catalog: Provider names and implementations to use; defaults to the built-ins.
         """
-        self.provider: Provider = _resolve_provider(provider)
+        self.provider: Provider = _resolve_provider(provider, catalog)
         self.profile: ProviderProfile = self.provider.profile
         self.model = model
         self.executor: CommandExecutor = executor if executor is not None else HostCommandExecutor()

{agentshim-0.18.3 → agentshim-0.20.0}/agentshim/core/__init__.py

@@ -95,9 +95,10 @@ from .mcp import (
     StdioMcpServer,
     install_config_file,
 )
-from .models import ModelSpec, ModelTable, context_window, default_models, model_spec
+from .models import ModelSpec, ModelTable
 from .permissions import ApprovalPolicy, NativeMode, NativePermissions
-from .pricing import ModelPricing, PricingTable, cost_usd, default_pricing, price_for
+from .plugin import ConnectionOptions, PricingContext, ProviderPlugin, ProviderTestSupport
+from .pricing import ModelPricing, PricingTable, cost_usd
 from .profile import (
     ConfigScope,
     McpMechanism,
@@ -148,6 +149,7 @@ __all__ = [
     "CompositeEventHandler",
     "ConfigFileInstallation",
     "ConfigScope",
+    "ConnectionOptions",
     "ConsoleEventHandler",
     "ContextualStreamParser",
     "Continuity",
@@ -188,13 +190,16 @@ __all__ = [
     "ParsedTurn",
     "ParserContext",
     "PolicyConfig",
+    "PricingContext",
     "PricingTable",
     "ProcessClosedError",
     "Provider",
     "ProviderCapabilityError",
     "ProviderError",
+    "ProviderPlugin",
     "ProviderProfile",
     "ProviderStatus",
+    "ProviderTestSupport",
     "ProviderUsage",
     "RandomIds",
     "RateLimitStatus",
@@ -245,20 +250,15 @@ __all__ = [
     "UsageReport",
     "compact_json",
     "compose_event_handlers",
-    "context_window",
     "cost_usd",
-    "default_models",
-    "default_pricing",
     "dialect_problems",
     "host_auth_plan",
     "install_config_file",
     "interactive_env",
     "materialize",
-    "model_spec",
     "normalize",
     "normalized_usage",
     "parse_json_object",
     "plan_auth",
     "prepare_config_home",
-    "price_for",
 ]

agentshim-0.20.0/agentshim/core/models.py

@@ -0,0 +1,153 @@
+"""Provider-independent model facts and tables."""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass, field, replace
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    """One model's context window, with where and when it was read.
+
+    Attributes:
+        vendor: Who serves the model (``"openai"``, ``"anthropic"``).
+        model: The model id as the vendor names it.
+        context_window: The model's context window in tokens (input and
+            output together), at the vendor's default for that id.
+        source: URL of the official page the number was read from.
+        checked: Date the number was last checked against ``source``.
+        display_name: A readable name for the model (``"Opus 5.5"``), or
+            ``None`` for a caller-built entry that has none.
+        family: The model line the model belongs to (``"Claude"``, ``"GPT"``,
+            ``"Gemini"``); set together with ``display_name``.
+        tier: The model's rank within its family, ``1`` the smallest and
+            cheapest; versions of one tier share a rank. ``None`` for a model
+            that sits on no tier ladder.
+        tier_name: The tier's readable name (``"Opus"``); set together with
+            ``tier``.
+    """
+
+    vendor: str
+    model: str
+    context_window: int
+    source: str
+    checked: dt.date
+    display_name: str | None = None
+    family: str | None = None
+    tier: int | None = None
+    tier_name: str | None = None
+
+    def __post_init__(self) -> None:
+        """Reject a missing name, source or date, and a window that is not a positive int."""
+        for name in ("vendor", "model"):
+            value: object = getattr(self, name)
+            if not isinstance(value, str) or not value.strip():
+                msg = f"{name} must be a non-empty string"
+                raise ValueError(msg)
+        source = cast("object", self.source)
+        if not isinstance(source, str) or not source.startswith("https://"):
+            msg = f"{self.vendor}/{self.model}: source must be an https:// URL"
+            raise ValueError(msg)
+        checked = cast("object", self.checked)
+        if not isinstance(checked, dt.date) or isinstance(checked, dt.datetime):
+            msg = f"{self.vendor}/{self.model}: checked must be a datetime.date"
+            raise TypeError(msg)
+        window = cast("object", self.context_window)
+        if isinstance(window, bool) or not isinstance(window, int) or window <= 0:
+            msg = f"{self.vendor}/{self.model}: context_window must be a positive int"
+            raise ValueError(msg)
+        self._check_presentation()
+
+    def _check_presentation(self) -> None:
+        """Reject a half-set name pair or tier pair, and a tier that is not a positive int."""
+        for first, second in (("display_name", "family"), ("tier", "tier_name")):
+            if (getattr(self, first) is None) != (getattr(self, second) is None):
+                msg = f"{self.vendor}/{self.model}: {first} and {second} are set together"
+                raise ValueError(msg)
+        for name in ("display_name", "family", "tier_name"):
+            value: object = getattr(self, name)
+            if value is not None and (not isinstance(value, str) or not value.strip()):
+                msg = f"{self.vendor}/{self.model}: {name} must be a non-empty string"
+                raise ValueError(msg)
+        tier = cast("object", self.tier)
+        if tier is not None and (isinstance(tier, bool) or not isinstance(tier, int) or tier < 1):
+            msg = f"{self.vendor}/{self.model}: tier must be a positive int"
+            raise ValueError(msg)
+        if self.tier is not None and self.family is None:
+            msg = f"{self.vendor}/{self.model}: tier needs a family"
+            raise ValueError(msg)
+
+    @property
+    def key(self) -> tuple[str, str]:
+        """The ``(vendor, model)`` this entry describes."""
+        return (self.vendor, self.model)
+
+
+@dataclass(frozen=True)
+class ModelTable:
+    """A versioned set of :class:`ModelSpec` entries.
+
+    Attributes:
+        version: Names this set of facts; change it whenever a fact changes.
+        last_updated: Date the table as a whole was last updated. No entry
+            may have been checked later.
+        entries: One entry per ``(vendor, model)``.
+    """
+
+    version: str
+    last_updated: dt.date
+    entries: tuple[ModelSpec, ...] = field(default=())
+
+    def __post_init__(self) -> None:
+        """Reject a missing version, duplicate keys, and entries checked after ``last_updated``."""
+        version = cast("object", self.version)
+        if not isinstance(version, str) or not version.strip():
+            msg = "version must be a non-empty string"
+            raise ValueError(msg)
+        object.__setattr__(self, "entries", tuple(self.entries))
+        seen: set[tuple[str, str]] = set()
+        for entry in self.entries:
+            if not isinstance(cast("object", entry), ModelSpec):
+                msg = f"entries must be ModelSpec, got {entry!r}"
+                raise TypeError(msg)
+            if entry.key in seen:
+                msg = f"duplicate model entry for {entry.vendor}/{entry.model}"
+                raise ValueError(msg)
+            seen.add(entry.key)
+            if entry.checked > self.last_updated:
+                msg = (
+                    f"{entry.vendor}/{entry.model} was checked {entry.checked}, "
+                    f"after the table's last_updated {self.last_updated}"
+                )
+                raise ValueError(msg)
+
+    def get(self, vendor: str, model: str) -> ModelSpec | None:
+        """The entry for exactly ``(vendor, model)``, or ``None``."""
+        for entry in self.entries:
+            if entry.key == (vendor, model):
+                return entry
+        return None
+
+    def with_entries(
+        self,
+        entries: Iterable[ModelSpec],
+        *,
+        version: str,
+        last_updated: dt.date | None = None,
+    ) -> ModelTable:
+        """A new table with *entries* added, replacing any with the same key."""
+        added = tuple(entries)
+        by_key = {entry.key: entry for entry in self.entries}
+        by_key.update({entry.key: entry for entry in added})
+        latest = max([self.last_updated, *(entry.checked for entry in added)])
+        return replace(
+            self,
+            version=version,
+            last_updated=last_updated or latest,
+            entries=tuple(by_key.values()),
+        )

agentshim-0.20.0/agentshim/core/plugin.py

@@ -0,0 +1,172 @@
+"""Method-based contract implemented by built-in and third-party plugins."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    import datetime as dt
+    from collections.abc import Callable, Mapping, Sequence
+    from pathlib import Path
+
+    from agentshim.execution.executor import CommandExecutor, CommandRequest
+
+    from .clock import Clock
+    from .conversation import Transport, TransportKind
+    from .errors import FailureKind
+    from .ids import IdAllocator
+    from .models import ModelSpec, ModelTable
+    from .pricing import ModelPricing, PricingTable
+    from .profile import ProviderProfile
+    from .provider import Provider
+    from .status import AuthState, ProviderStatus
+    from .usage import TokenUsage
+
+
+class ScriptedLines(Protocol):
+    """Build one turn of a provider's real stdout for consumer tests."""
+
+    def __call__(  # noqa: PLR0913
+        self,
+        *,
+        text: str = "",
+        session_id: str | None = None,
+        usage: TokenUsage | None = None,
+        tool_calls: Sequence[tuple[str, Mapping[str, Any], str]] = (),
+        structured_output: object | None = None,
+        skills_offered: Sequence[str] | None = None,
+        skills_invoked: Sequence[str] = (),
+    ) -> list[str]:
+        """Return stdout lines in this provider's stream format."""
+        ...
+
+
+class ResumeFailureLines(Protocol):
+    """Build the stream and exit status of a failed resume."""
+
+    def __call__(
+        self, *, session_id: str | None = None
+    ) -> tuple[Sequence[str], Sequence[str], int]:
+        """Return stdout, stderr, and exit status."""
+        ...
+
+
+class FailureLines(Protocol):
+    """Build the stream and exit status of a classified failure."""
+
+    def __call__(
+        self, kind: FailureKind, *, session_id: str | None = None
+    ) -> tuple[Sequence[str], Sequence[str], int]:
+        """Return stdout, stderr, and exit status."""
+        ...
+
+
+class StreamTransportFactory(Protocol):
+    """Legacy type for provider-internal stream constructors."""
+
+    def __call__(  # noqa: PLR0913
+        self,
+        *,
+        executor: CommandExecutor,
+        env: Mapping[str, str] | None,
+        clock: Clock,
+        ids: IdAllocator,
+        check_timeout: float,
+        log: Callable[[str], None] | None,
+    ) -> Transport:
+        """Create a stream transport."""
+        ...
+
+
+class ProbeFixture(Protocol):
+    """Build fake CLI output for a readiness command."""
+
+    def __call__(
+        self, args: Sequence[str], *, version: str, auth: AuthState
+    ) -> tuple[str, str, int]:
+        """Return stdout, stderr, and exit status."""
+        ...
+
+
+@dataclass(frozen=True)
+class ProviderTestSupport:
+    """Optional provider-owned adapters for the generic test helpers."""
+
+    scripted_lines: ScriptedLines
+    resume_failure_lines: ResumeFailureLines
+    failure_lines: FailureLines | None = None
+    installed_mcp_servers: Callable[[CommandRequest, Path], dict[str, dict[str, Any]]] | None = None
+    probe_fixture: ProbeFixture | None = None
+
+
+@dataclass(frozen=True)
+class ConnectionOptions:
+    """Dependencies for a requested connection mode."""
+
+    kind: TransportKind
+    executor: CommandExecutor | None = None
+    env: Mapping[str, str] | None = None
+    clock: Clock | None = None
+    ids: IdAllocator | None = None
+    check_timeout: float = 15.0
+    log: Callable[[str], None] | None = None
+
+
+@dataclass(frozen=True)
+class PricingContext:
+    """Conditions under which a rate is requested; omitted values mean standard tier."""
+
+    as_of: dt.date | None = None
+    region: str | None = None
+    tier: str | None = None
+
+
+@runtime_checkable
+class ProviderPlugin(Protocol):
+    """Required methods for every provider; unsupported facts return ``None``."""
+
+    @property
+    def name(self) -> str:
+        """Stable catalog key."""
+        ...
+
+    def describe(self) -> ProviderProfile:
+        """Describe capabilities independently of local installation state."""
+        ...
+
+    def connection_modes(self) -> frozenset[TransportKind]:
+        """Declare which connection modes ``connect`` accepts."""
+        ...
+
+    def connect(self, options: ConnectionOptions) -> Provider | Transport:
+        """Create the requested one-shot provider or stream transport."""
+        ...
+
+    def probe(
+        self, executor: CommandExecutor, env: Mapping[str, str], timeout: float
+    ) -> ProviderStatus:
+        """Check readiness on the supplied executor, without running a model."""
+        ...
+
+    def model_info(self, model: str, table: ModelTable | None = None) -> ModelSpec | None:
+        """Resolve context-window facts; *table* overrides built-in facts."""
+        ...
+
+    def pricing_info(
+        self, model: str, context: PricingContext, table: PricingTable | None = None
+    ) -> ModelPricing | None:
+        """Resolve a rate for *model* and *context*, or report it unknown."""
+        ...
+
+    def known_models(self) -> tuple[ModelSpec, ...]:
+        """Enumerate facts available for a reproducible table snapshot."""
+        ...
+
+    def known_prices(self) -> tuple[ModelPricing, ...]:
+        """Enumerate standard-tier prices for a reproducible table snapshot."""
+        ...
+
+    def test_support(self) -> ProviderTestSupport | None:
+        """Return consumer-test adapters, if provided."""
+        ...