agentshim 0.12.0__tar.gz → 0.13.0__tar.gz

{agentshim-0.12.0 → agentshim-0.13.0}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.13.0 (2026-10-03)
+
+A session can leave out the user's own CLI configuration. Additive.
+
+### Added
+
+- `ConfigScope` (`ALL`, `PROJECT`) as a session option on `start_session` and
+  `run`, `ProviderProfile.config_scopes`, and `ArgvContext.config_scope`.
+  `PROJECT` keeps the user's settings, hooks, global instructions, notify
+  commands, profiles and memory out of every turn. Claude Code:
+  `--setting-sources project,local` and `autoMemoryEnabled=false`. Codex: a
+  dedicated `CODEX_HOME` plus `--ignore-user-config --disable memories`;
+  `build_argv` refuses the scope in the user's own home. Copilot, Gemini and
+  opencode refuse it.
+- `ProviderProfile.config_home_files` and `prepare_config_home`, which build
+  that dedicated home holding only the login and return the environment that
+  points the CLI at it. The login is a symlink to the user's own `auth.json`,
+  so a refresh token Codex rotates in either home stays valid in both.
+
 ## 0.12.0 (2026-10-03)
 
 A turn whose output never matched its schema says so. Additive except that

{agentshim-0.12.0 → agentshim-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.12.0
+Version: 0.13.0
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
 Requires-Dist: tomli>=2; python_full_version < '3.11'

{agentshim-0.12.0 → agentshim-0.13.0}/agentshim/__init__.py

@@ -19,6 +19,7 @@ from .core import (
     CliTimeoutError,
     CompositeEventHandler,
     ConfigFileInstallation,
+    ConfigScope,
     ConsoleEventHandler,
     EventHandlerBase,
     FailureKind,
@@ -79,6 +80,7 @@ from .core import (
     normalize,
     normalized_usage,
     parse_json_object,
+    prepare_config_home,
     price_for,
 )
 from .execution import (
@@ -99,7 +101,7 @@ from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
 
-__version__ = "0.12.0"
+__version__ = "0.13.0"
 
 __all__ = [
     "AgentEvent",
@@ -125,6 +127,7 @@ __all__ = [
     "CommandStreamSink",
     "CompositeEventHandler",
     "ConfigFileInstallation",
+    "ConfigScope",
     "ConsoleEventHandler",
     "CopilotProvider",
     "EventHandlerBase",
@@ -194,6 +197,7 @@ __all__ = [
     "normalize",
     "normalized_usage",
     "parse_json_object",
+    "prepare_config_home",
     "price_for",
     "provider_names",
 ]

{agentshim-0.12.0 → agentshim-0.13.0}/agentshim/agent.py

@@ -24,6 +24,7 @@ from agentshim.core.errors import (
 )
 from agentshim.core.events import RunFinished, RunStarted, compose_event_handlers
 from agentshim.core.profile import (
+    ConfigScope,
     McpMechanism,
     McpScope,
     OutputSchemaStyle,
@@ -114,7 +115,7 @@ class CliAgent:
         self.executor.check_binary(self.binary_path, self.env, timeout=check_timeout)
         self.log(f"{self.profile.display_name} ready at {self.binary_path}")
 
-    def start_session(
+    def start_session(  # noqa: PLR0913 - one keyword per independent session option
         self,
         *,
         cwd: str | None = None,
@@ -122,11 +123,12 @@ class CliAgent:
         session_id: str | None = None,
         skill_scope: SkillScope = SkillScope.ALL,
         mcp_scope: McpScope = McpScope.ALL,
+        config_scope: ConfigScope = ConfigScope.ALL,
     ) -> AgentSession:
         """Open a conversation whose turns resume one another.
 
-        ``skill_scope`` and ``mcp_scope`` are fixed for the conversation (see
-        ``AgentSession``).
+        ``skill_scope``, ``mcp_scope`` and ``config_scope`` are fixed for the
+        conversation (see ``AgentSession``).
         """
         return AgentSession(
             self,
@@ -135,9 +137,10 @@ class CliAgent:
             session_id=session_id,
             skill_scope=skill_scope,
             mcp_scope=mcp_scope,
+            config_scope=config_scope,
         )
 
-    def run(
+    def run(  # noqa: PLR0913 - one keyword per independent session option
         self,
         request: TurnRequest | str,
         *,
@@ -145,10 +148,15 @@ class CliAgent:
         timeout: float | None = None,
         skill_scope: SkillScope = SkillScope.ALL,
         mcp_scope: McpScope = McpScope.ALL,
+        config_scope: ConfigScope = ConfigScope.ALL,
     ) -> TurnResult:
         """Run one turn in a throwaway session."""
         session = self.start_session(
-            cwd=cwd, timeout=timeout, skill_scope=skill_scope, mcp_scope=mcp_scope
+            cwd=cwd,
+            timeout=timeout,
+            skill_scope=skill_scope,
+            mcp_scope=mcp_scope,
+            config_scope=config_scope,
         )
         return session.turn(request)
 
@@ -169,6 +177,7 @@ class AgentSession:
         session_id: str | None = None,
         skill_scope: SkillScope = SkillScope.ALL,
         mcp_scope: McpScope = McpScope.ALL,
+        config_scope: ConfigScope = ConfigScope.ALL,
     ) -> None:
         """Bind a conversation to one agent, with per-turn defaults.
 
@@ -183,6 +192,11 @@ class AgentSession:
         limits which MCP servers every turn's CLI may connect to
         (``McpScope.SESSION``: only those in ``TurnRequest.mcp_servers``) and
         is checked against ``profile.mcp_scopes`` the same way.
+        ``config_scope`` limits which of the user's own CLI configuration
+        (settings, hooks, global instructions, memory) every turn loads, and
+        is checked against ``profile.config_scopes``; a provider with
+        ``profile.config_home_files`` additionally needs its state root
+        pointed at a home from ``prepare_config_home``.
         """
         if skill_scope not in agent.profile.skill_scopes:
             msg = f"{agent.profile.name} cannot limit skills to scope {skill_scope.value!r}"
@@ -190,7 +204,11 @@ class AgentSession:
         if mcp_scope not in agent.profile.mcp_scopes:
             msg = f"{agent.profile.name} cannot limit MCP servers to scope {mcp_scope.value!r}"
             raise ProviderCapabilityError(msg)
+        if config_scope not in agent.profile.config_scopes:
+            msg = f"{agent.profile.name} cannot limit user configuration to scope {config_scope.value!r}"
+            raise ProviderCapabilityError(msg)
         self.skill_scope = skill_scope
+        self.config_scope = config_scope
         self.mcp_scope = mcp_scope
         self._agent = agent
         self._cwd = cwd
@@ -302,6 +320,7 @@ class AgentSession:
                     cwd=cwd,
                     skill_scope=self.skill_scope,
                     mcp_scope=self.mcp_scope,
+                    config_scope=self.config_scope,
                     mcp_servers=tuple(req.mcp_servers),
                 )
             )

{agentshim-0.12.0 → agentshim-0.13.0}/agentshim/core/__init__.py

@@ -43,6 +43,7 @@ from .events import (
     UsageReport,
     compose_event_handlers,
 )
+from .home import prepare_config_home
 from .mcp import (
     ConfigFileInstallation,
     FlagsInstallation,
@@ -55,6 +56,7 @@ from .mcp import (
 )
 from .pricing import ModelPricing, PricingTable, cost_usd, default_pricing, price_for
 from .profile import (
+    ConfigScope,
     McpMechanism,
     McpScope,
     OutputSchemaStyle,
@@ -82,6 +84,7 @@ __all__ = [
     "CliTimeoutError",
     "CompositeEventHandler",
     "ConfigFileInstallation",
+    "ConfigScope",
     "ConsoleEventHandler",
     "EventHandlerBase",
     "FailureKind",
@@ -142,5 +145,6 @@ __all__ = [
     "normalize",
     "normalized_usage",
     "parse_json_object",
+    "prepare_config_home",
     "price_for",
 ]

agentshim-0.13.0/agentshim/core/home.py

@@ -0,0 +1,90 @@
+"""Dedicated CLI homes for ``ConfigScope.PROJECT``.
+
+Some CLIs read the user's global instructions, hooks and memory from their
+state root (Codex: ``$CODEX_HOME/AGENTS.md``, ``hooks.json``, ``memories/``)
+with no flag to skip them. The only way to keep them out is to run the CLI
+against another state root that holds nothing but the credentials. That root
+is the caller's to own, because the CLI keeps its conversations there too: a
+session resumes only from the home it started in.
+
+The credentials are linked, not copied. Codex rotates its OAuth refresh token
+on refresh (the server rejects a reused one with ``refresh_token_reused``) and
+saves ``auth.json`` by opening it with ``O_TRUNC`` and writing in place
+(codex-rs ``login/src/auth/storage.rs``, ``FileAuthStorage::save``), which
+follows a symlink. A copy would strand one of the two logins after the first
+refresh; a link keeps a single file that every process rereads before it
+refreshes (``AuthManager::refresh_token``'s guarded reload).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ._files import real_path
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from .profile import ProviderProfile
+
+
+def state_root(profile: ProviderProfile, env: Mapping[str, str]) -> Path | None:
+    """The state root the CLI run with *env* reads, or ``None`` if it has none.
+
+    ``$<state_root_env>`` when set, else ``$HOME/<state_dirs[0]>``.
+    """
+    if profile.state_root_env and env.get(profile.state_root_env):
+        return Path(env[profile.state_root_env]).expanduser()
+    if not profile.state_dirs:
+        return None
+    home = env.get("HOME") or os.path.expanduser("~")  # noqa: PTH111 - a str contract, not a Path
+    return Path(home) / profile.state_dirs[0]
+
+
+def prepare_config_home(
+    profile: ProviderProfile, home: Path, env: Mapping[str, str]
+) -> dict[str, str]:
+    """Make *home* a state root holding only the credentials, and point at it.
+
+    Links each of ``profile.config_home_files`` that exists in the state root
+    *env* selects into *home* as a symlink to that file's real path (replacing
+    whatever was there, such as a copy from an older agentshim), so a token
+    the CLI refreshes in either home is the one both read next. Returns the
+    environment overrides that make the CLI use *home*. A sandbox that runs
+    the CLI must expose the link's target read-write. Everything else in *home* (conversations, caches) is the
+    CLI's own and is left alone. A provider with no ``config_home_files``
+    isolates by flags alone: nothing is written and the result is empty.
+
+    Raises:
+        ValueError: *home* is not absolute, or is the state root *env*
+            already selects, which would isolate nothing.
+    """
+    if not profile.config_home_files:
+        return {}
+    if not home.is_absolute():
+        msg = f"{profile.name} config home must be an absolute path, got {home}"
+        raise ValueError(msg)
+    assert profile.state_root_env is not None, "config_home_files needs a state_root_env"  # noqa: S101 - profile invariant
+    source = state_root(profile, env)
+    if source is not None and real_path(source) == real_path(home):
+        msg = f"{profile.name} config home {home} is the user's own state root"
+        raise ValueError(msg)
+    home.mkdir(parents=True, exist_ok=True)
+    for name in profile.config_home_files:
+        origin = None if source is None else source / name
+        if origin is not None and origin.is_file():
+            _link(home / name, real_path(origin))
+    return {profile.state_root_env: str(home)}
+
+
+def _link(link: Path, target: Path) -> None:
+    """Point *link* at *target*, atomically replacing any file already there."""
+    if link.is_symlink() and link.readlink() == target:
+        return
+    link.parent.mkdir(parents=True, exist_ok=True)
+    staged = link.with_name(f".{link.name}.{os.getpid()}.link")
+    staged.unlink(missing_ok=True)
+    staged.symlink_to(target)
+    staged.replace(link)

{agentshim-0.12.0 → agentshim-0.13.0}/agentshim/core/profile.py

@@ -93,6 +93,26 @@ class McpScope(Enum):
     SESSION = "session"
 
 
+class ConfigScope(Enum):
+    """Which of the user's own CLI configuration a session loads.
+
+    ``ALL``: whatever the CLI loads by default: the user's settings, hooks,
+    global instructions (``~/.claude/CLAUDE.md``, ``$CODEX_HOME/AGENTS.md``),
+    notify commands, profiles and memory. ``PROJECT``: none of that; the
+    session sees the workspace's own instructions and settings plus what
+    agentshim passes for the turn, so the user running agentshim does not
+    change what the agent does. Credentials keep working. A provider that
+    lists a ``ProviderProfile.config_home_files`` can only isolate through a
+    dedicated home: ``prepare_config_home`` builds it and returns the
+    environment that points the CLI at it. A provider declares the scopes it
+    can enforce in ``ProviderProfile.config_scopes``; asking for another one
+    is an error, never a silent ``ALL``.
+    """
+
+    ALL = "all"
+    PROJECT = "project"
+
+
 def _no_container_env() -> Mapping[str, str]:
     """Empty read-only default: a frozen spec must not carry a mutable one.
 
@@ -145,3 +165,10 @@ class ProviderProfile:
     skill_scopes: frozenset[SkillScope] = frozenset({SkillScope.ALL})
     #: The ``McpScope`` values a session on this provider may request.
     mcp_scopes: frozenset[McpScope] = frozenset({McpScope.ALL})
+    #: The ``ConfigScope`` values a session on this provider may request.
+    config_scopes: frozenset[ConfigScope] = frozenset({ConfigScope.ALL})
+    #: Files, relative to the state root (``state_dirs[0]``, or
+    #: ``$<state_root_env>``), that ``prepare_config_home`` copies into a
+    #: dedicated home for ``ConfigScope.PROJECT``. Empty when the provider
+    #: isolates by flags alone and needs no home.
+    config_home_files: tuple[str, ...] = ()

{agentshim-0.12.0 → agentshim-0.13.0}/agentshim/core/provider.py

@@ -6,7 +6,7 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Protocol
 
 from .errors import FailureKind
-from .profile import McpScope, SkillScope
+from .profile import ConfigScope, McpScope, SkillScope
 from .usage import ProviderUsage
 
 if TYPE_CHECKING:
@@ -49,6 +49,9 @@ class ArgvContext:
     #: A provider enforcing ``McpScope.SESSION`` renders them itself when its
     #: installed config file is not enough to exclude the user's own.
     mcp_servers: Sequence[McpServer] = ()
+    #: Which of the user's own CLI configuration the CLI may load; the
+    #: session has already checked that the provider's profile supports it.
+    config_scope: ConfigScope = ConfigScope.ALL
 
 
 @dataclass(frozen=True)

{agentshim-0.12.0 → agentshim-0.13.0}/agentshim/providers/claude/provider.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING, Any
 from agentshim.core.errors import FailureKind, ProviderCapabilityError, SessionResumeError
 from agentshim.core.mcp import HttpMcpServer, NoopInstallation, StdioMcpServer, install_config_file
 from agentshim.core.profile import (
+    ConfigScope,
     McpMechanism,
     McpScope,
     OutputSchemaStyle,
@@ -44,6 +45,14 @@ MCP_SERVER_KEY = "mcpServers"
 #: account connectors are not user settings and stay.
 PROJECT_SETTING_SOURCES = ("--setting-sources", "project,local")
 
+#: ``ConfigScope.PROJECT``: the same ``--setting-sources`` drops the user's
+#: settings (hooks, ``env``, permissions, default model), ``~/.claude/CLAUDE.md``
+#: and plugins; auto-memory is not a setting source and is switched off in the
+#: turn's ``--settings`` instead, so ``~/.claude/projects/*/memory`` is neither
+#: read nor written. Built-in skills, the workspace's ``CLAUDE.md``,
+#: ``.claude/`` settings and skills, and credentials keep working.
+NO_AUTO_MEMORY_SETTINGS = {"autoMemoryEnabled": False}
+
 #: ``McpScope.SESSION``: ``--strict-mcp-config`` makes ``--mcp-config`` the
 #: only source of MCP servers. It drops the user's and the project's
 #: (``.mcp.json``) servers, plugin servers and claude.ai account connectors,
@@ -75,6 +84,7 @@ PROFILE = ProviderProfile(
     skill_invocation=SkillSignal.STRUCTURED,
     skill_scopes=frozenset({SkillScope.ALL, SkillScope.PROJECT}),
     mcp_scopes=frozenset({McpScope.ALL, McpScope.SESSION}),
+    config_scopes=frozenset({ConfigScope.ALL, ConfigScope.PROJECT}),
     container_install=(
         "apt-get update && apt-get install -y --no-install-recommends curl ca-certificates",
         "curl -fsSL https://claude.ai/install.sh | bash",
@@ -138,7 +148,8 @@ class ClaudeProvider:
             "stream-json",
             "--verbose",
         ]
-        if ctx.skill_scope is SkillScope.PROJECT:
+        isolate_config = ctx.config_scope is ConfigScope.PROJECT
+        if ctx.skill_scope is SkillScope.PROJECT or isolate_config:
             argv += PROJECT_SETTING_SOURCES
         if ctx.model:
             argv += ["--model", ctx.model]
@@ -147,6 +158,8 @@ class ClaudeProvider:
         if ctx.schema_inline:
             argv += ["--json-schema", ctx.schema_inline]
         settings = build_settings(self.sandbox, hooks=self.hooks)
+        if isolate_config:
+            settings.update(NO_AUTO_MEMORY_SETTINGS)
         if settings:
             argv += ["--settings", json.dumps(settings)]
         if ctx.mcp_scope is McpScope.SESSION:

{agentshim-0.12.0 → agentshim-0.13.0}/agentshim/providers/codex/provider.py

@@ -7,8 +7,10 @@ import re
 from typing import TYPE_CHECKING, Any
 
 from agentshim.core.errors import ProviderCapabilityError, SessionResumeError
+from agentshim.core.home import state_root
 from agentshim.core.mcp import FlagsInstallation, HttpMcpServer, NoopInstallation
 from agentshim.core.profile import (
+    ConfigScope,
     McpMechanism,
     McpScope,
     OutputSchemaStyle,
@@ -85,6 +87,10 @@ PROFILE = ProviderProfile(
     skill_invocation=SkillSignal.INFERRED,
     skill_scopes=frozenset({SkillScope.ALL, SkillScope.PROJECT}),
     mcp_scopes=frozenset({McpScope.ALL, McpScope.SESSION}),
+    config_scopes=frozenset({ConfigScope.ALL, ConfigScope.PROJECT}),
+    # Codex reads AGENTS.md, hooks.json and memories/ from $CODEX_HOME with no
+    # flag to skip them, so ConfigScope.PROJECT needs a home of its own.
+    config_home_files=("auth.json",),
     container_install=(_NODE_INSTALL, _CODEX_INSTALL),
     # Documented Codex CLI variable that relocates ~/.codex (``codex --help``:
     # "Layer $CODEX_HOME/<name>.config.toml on top of the base user config";
@@ -105,6 +111,13 @@ BYPASS_FLAG = "--dangerously-bypass-approvals-and-sandbox"
 #: Keeps user and project ``.rules`` files out of a sandboxed turn.
 IGNORE_RULES_FLAG = "--ignore-rules"
 
+#: ``ConfigScope.PROJECT``: ``$CODEX_HOME/config.toml`` (profiles, notify,
+#: ``developer_instructions``, project trust) is not loaded, and the memories
+#: Codex would otherwise write and reread across sessions in the home stay
+#: off. The global ``AGENTS.md``, ``hooks.json`` and existing memories are
+#: kept out by the dedicated home itself (``prepare_config_home``).
+PROJECT_CONFIG_FLAGS = ("--ignore-user-config", "--disable", "memories")
+
 
 class CodexProvider:
     """Codex (``codex exec --json``). ``sandbox`` is a provider option."""
@@ -136,6 +149,9 @@ class CodexProvider:
         if ctx.model:
             argv += ["--model", ctx.model]
         argv += _shell_path_config(ctx.env)
+        if ctx.config_scope is ConfigScope.PROJECT:
+            _check_config_home(ctx)
+            argv += PROJECT_CONFIG_FLAGS
         argv += _scope_overrides(ctx)
         if ctx.reasoning_effort:
             argv += ["--config", f"model_reasoning_effort={toml_str(ctx.reasoning_effort)}"]
@@ -250,6 +266,26 @@ def _writable_dirs(config: CodexSandboxConfig, ctx: ArgvContext) -> list[str]:
     return dirs
 
 
+def _check_config_home(ctx: ArgvContext) -> None:
+    """Refuse ``ConfigScope.PROJECT`` unless the turn runs in a home of its own.
+
+    The user's global ``AGENTS.md``, hooks and memories live in the state root
+    and no flag skips them, so a turn still pointed at the user's root would
+    load them while claiming to be isolated.
+    """
+    home = ctx.env.get("CODEX_HOME")
+    if not home or not os.path.isabs(home):  # noqa: PTH117 - a str contract, not a Path
+        msg = (
+            "ConfigScope.PROJECT needs CODEX_HOME set to the absolute path of a "
+            f"dedicated home prepared with prepare_config_home (got {home!r})"
+        )
+        raise ProviderCapabilityError(msg)
+    user_root = state_root(PROFILE, {key: v for key, v in ctx.env.items() if key != "CODEX_HOME"})
+    if user_root is not None and os.path.realpath(home) == os.path.realpath(user_root):
+        msg = f"ConfigScope.PROJECT needs a dedicated CODEX_HOME, not the user's own {home}"
+        raise ProviderCapabilityError(msg)
+
+
 def _is_within(path: str, directory: str) -> bool:
     resolved, parent = os.path.realpath(path), os.path.realpath(directory)
     return resolved == parent or resolved.startswith(parent.rstrip(os.sep) + os.sep)

{agentshim-0.12.0 → agentshim-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentshim"
-version = "0.12.0"
+version = "0.13.0"
 description = "Provider-agnostic coding-agent CLI shims"
 readme = "README.md"
 requires-python = ">=3.10"