agentshim 0.8.0__tar.gz → 0.9.0__tar.gz

{agentshim-0.8.0 → agentshim-0.9.0}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.9.0 (2026-10-03)
+
+Skill isolation. Additive: the default scope keeps today's behaviour.
+
+### Added
+
+- `SkillScope` (`ALL`, `PROJECT`) and `start_session(skill_scope=...)` /
+  `run(skill_scope=...)`. `PROJECT` offers only the workspace's skills and
+  the CLI's built-in ones, not the user's personal skills or plugins.
+- `ProviderProfile.skill_scopes` declares the scopes a provider enforces;
+  asking for another raises `ProviderCapabilityError` from `start_session`.
+- `ArgvContext.skill_scope` carries the session's scope to `build_argv`.
+- Claude Code: `PROJECT` passes `--setting-sources project,local`, which also
+  skips user settings and `~/.claude/CLAUDE.md`; credentials still work.
+- Codex: `PROJECT` sets `features.plugins=false` and disables every user
+  `SKILL.md` (`$CODEX_HOME/skills` except `.system`, `~/.agents/skills`)
+  through `skills.config`.
+- Gemini, opencode and Copilot support `ALL` only.
+- Live e2e: `SkillScope.PROJECT` hides a skill seeded in a relocated user
+  home while the workspace skill stays offered (`tests/e2e/test_skills_e2e.py`).
+
 ## 0.8.0 (2026-10-03)
 
 Skill observability. Additive: a caller that ignores the new events and the

{agentshim-0.8.0 → agentshim-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.8.0
+Version: 0.9.0
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
 Provides-Extra: test

{agentshim-0.8.0 → agentshim-0.9.0}/agentshim/__init__.py

@@ -50,6 +50,7 @@ from .core import (
     SessionResumeError,
     SessionStarted,
     SkillInvoked,
+    SkillScope,
     SkillsDiscovered,
     SkillSignal,
     SkillSummary,
@@ -96,7 +97,7 @@ from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 
 __all__ = [
     "AgentEvent",
@@ -159,6 +160,7 @@ __all__ = [
     "SessionResumeError",
     "SessionStarted",
     "SkillInvoked",
+    "SkillScope",
     "SkillSignal",
     "SkillSummary",
     "SkillTracker",

{agentshim-0.8.0 → agentshim-0.9.0}/agentshim/agent.py

@@ -23,7 +23,7 @@ from agentshim.core.errors import (
     SessionResumeError,
 )
 from agentshim.core.events import RunFinished, RunStarted, compose_event_handlers
-from agentshim.core.profile import McpMechanism, OutputSchemaStyle, SchemaDialect
+from agentshim.core.profile import McpMechanism, OutputSchemaStyle, SchemaDialect, SkillScope
 from agentshim.core.provider import ArgvContext
 from agentshim.core.schema import compact_json, dialect_problems, materialize
 from agentshim.core.skills import SkillTracker
@@ -114,9 +114,15 @@ class CliAgent:
         cwd: str | None = None,
         timeout: float | None = None,
         session_id: str | None = None,
+        skill_scope: SkillScope = SkillScope.ALL,
     ) -> AgentSession:
-        """Open a conversation whose turns resume one another."""
-        return AgentSession(self, cwd=cwd, timeout=timeout, session_id=session_id)
+        """Open a conversation whose turns resume one another.
+
+        ``skill_scope`` is fixed for the conversation (see ``AgentSession``).
+        """
+        return AgentSession(
+            self, cwd=cwd, timeout=timeout, session_id=session_id, skill_scope=skill_scope
+        )
 
     def run(
         self,
@@ -124,9 +130,11 @@ class CliAgent:
         *,
         cwd: str | None = None,
         timeout: float | None = None,
+        skill_scope: SkillScope = SkillScope.ALL,
     ) -> TurnResult:
         """Run one turn in a throwaway session."""
-        return self.start_session(cwd=cwd, timeout=timeout).turn(request)
+        session = self.start_session(cwd=cwd, timeout=timeout, skill_scope=skill_scope)
+        return session.turn(request)
 
 
 def _discard(message: str) -> None:
@@ -143,6 +151,7 @@ class AgentSession:
         cwd: str | None = None,
         timeout: float | None = None,
         session_id: str | None = None,
+        skill_scope: SkillScope = SkillScope.ALL,
     ) -> None:
         """Bind a conversation to one agent, with per-turn defaults.
 
@@ -150,8 +159,15 @@ class AgentSession:
         successive turns resume one another. ``cwd`` and ``timeout`` are
         defaults an individual ``TurnRequest`` may override. Passing
         ``session_id`` adopts a conversation the provider already has, so the
-        first turn resumes rather than starts fresh.
+        first turn resumes rather than starts fresh. ``skill_scope`` limits
+        which skills every turn's CLI may discover; a scope the provider's
+        ``profile.skill_scopes`` does not list raises
+        ``ProviderCapabilityError`` here, before any turn runs.
         """
+        if skill_scope not in agent.profile.skill_scopes:
+            msg = f"{agent.profile.name} cannot limit skills to scope {skill_scope.value!r}"
+            raise ProviderCapabilityError(msg)
+        self.skill_scope = skill_scope
         self._agent = agent
         self._cwd = cwd
         self._timeout = timeout
@@ -260,6 +276,7 @@ class AgentSession:
                     mcp_argv=installation.argv,
                     extra_args=req.extra_args,
                     cwd=cwd,
+                    skill_scope=self.skill_scope,
                 )
             )
             command = CommandRequest(argv=argv, stdin=req.prompt, cwd=cwd, env=env, timeout=timeout)

{agentshim-0.8.0 → agentshim-0.9.0}/agentshim/core/__init__.py

@@ -58,6 +58,7 @@ from .profile import (
     OutputSchemaStyle,
     ProviderProfile,
     SchemaDialect,
+    SkillScope,
     SkillSignal,
 )
 from .provider import ArgvContext, McpInstallation, ParsedTurn, Provider, StreamParser
@@ -110,6 +111,7 @@ __all__ = [
     "SessionResumeError",
     "SessionStarted",
     "SkillInvoked",
+    "SkillScope",
     "SkillSignal",
     "SkillSummary",
     "SkillTracker",

{agentshim-0.8.0 → agentshim-0.9.0}/agentshim/core/profile.py

@@ -61,6 +61,22 @@ class SkillSignal(Enum):
     INFERRED = "inferred"
 
 
+class SkillScope(Enum):
+    """Which skills a session's CLI may discover.
+
+    ``ALL``: whatever the CLI finds by default, including the user's own
+    skills and installed plugins. ``PROJECT``: only the skills under the
+    session's working directory (the profile's ``skill_dirs``) plus the
+    CLI's built-in ones, so the user running agentshim does not change what
+    the agent is offered. A provider declares the scopes it can enforce in
+    ``ProviderProfile.skill_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.
 
@@ -109,3 +125,5 @@ class ProviderProfile:
     skill_discovery: SkillSignal = SkillSignal.NONE
     #: Whether the stream reveals skill loads (``SkillInvoked``).
     skill_invocation: SkillSignal = SkillSignal.NONE
+    #: The ``SkillScope`` values a session on this provider may request.
+    skill_scopes: frozenset[SkillScope] = frozenset({SkillScope.ALL})

{agentshim-0.8.0 → agentshim-0.9.0}/agentshim/core/provider.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Protocol
 
+from .profile import SkillScope
 from .usage import ProviderUsage
 
 if TYPE_CHECKING:
@@ -37,6 +38,9 @@ class ArgvContext:
     #: The directory the CLI will run in, or ``None`` for the executor's own.
     #: Argv never carries it; a provider reads it to validate paths against it.
     cwd: str | None = None
+    #: Which skills the CLI may discover; the session has already checked
+    #: that the provider's profile supports it.
+    skill_scope: SkillScope = SkillScope.ALL
 
 
 @dataclass(frozen=True)

{agentshim-0.8.0 → agentshim-0.9.0}/agentshim/providers/claude/provider.py

@@ -12,6 +12,7 @@ from agentshim.core.profile import (
     OutputSchemaStyle,
     ProviderProfile,
     SchemaDialect,
+    SkillScope,
     SkillSignal,
 )
 
@@ -31,6 +32,17 @@ if TYPE_CHECKING:
 MCP_CONFIG_FILENAME = ".mcp.json"
 MCP_SERVER_KEY = "mcpServers"
 
+#: ``SkillScope.PROJECT``: load settings only from the workspace's
+#: ``.claude/settings.json`` and ``.claude/settings.local.json`` (plus
+#: ``--settings`` and managed policy, which always apply). Leaving out the
+#: ``user`` source drops ``~/.claude/skills``, the user's plugins (with their
+#: skills, hooks and MCP servers), ``~/.claude/CLAUDE.md`` and the user's
+#: settings (default model, permissions, hooks, ``env``, ``apiKeyHelper``).
+#: Credentials are not settings: OAuth in ``.credentials.json`` and the
+#: ``auth_env_vars`` keep working. Claude Code's built-in skills and claude.ai
+#: account connectors are not user settings and stay.
+PROJECT_SETTING_SOURCES = ("--setting-sources", "project,local")
+
 PROFILE = ProviderProfile(
     name="claude",
     display_name="Claude Code",
@@ -54,6 +66,7 @@ PROFILE = ProviderProfile(
     # ``system/init`` lists ``skills``; the ``Skill`` tool call names one.
     skill_discovery=SkillSignal.STRUCTURED,
     skill_invocation=SkillSignal.STRUCTURED,
+    skill_scopes=frozenset({SkillScope.ALL, SkillScope.PROJECT}),
     container_install=(
         "apt-get update && apt-get install -y --no-install-recommends curl ca-certificates",
         "curl -fsSL https://claude.ai/install.sh | bash",
@@ -117,6 +130,8 @@ class ClaudeProvider:
             "stream-json",
             "--verbose",
         ]
+        if ctx.skill_scope is SkillScope.PROJECT:
+            argv += PROJECT_SETTING_SOURCES
         if ctx.model:
             argv += ["--model", ctx.model]
         if ctx.reasoning_effort:

{agentshim-0.8.0 → agentshim-0.9.0}/agentshim/providers/codex/provider.py

@@ -13,6 +13,7 @@ from agentshim.core.profile import (
     OutputSchemaStyle,
     ProviderProfile,
     SchemaDialect,
+    SkillScope,
     SkillSignal,
 )
 
@@ -20,6 +21,7 @@ from ._toml import toml_array, toml_str, unescape_toml
 from .parser import CodexStreamParser
 from .rules import RULES_FILENAME
 from .sandbox import CodexSandboxConfig, resolve_sandbox, sandbox_overrides
+from .skills import project_scope_overrides
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping, Sequence
@@ -79,6 +81,7 @@ PROFILE = ProviderProfile(
     # ``exec --json`` lists no skills; a load is inferred from a shell read
     # of a ``SKILL.md`` (``skills.py``).
     skill_invocation=SkillSignal.INFERRED,
+    skill_scopes=frozenset({SkillScope.ALL, SkillScope.PROJECT}),
     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";
@@ -130,6 +133,8 @@ class CodexProvider:
         if ctx.model:
             argv += ["--model", ctx.model]
         argv += _shell_path_config(ctx.env)
+        if ctx.skill_scope is SkillScope.PROJECT:
+            argv += project_scope_overrides(ctx.env)
         if ctx.reasoning_effort:
             argv += ["--config", f"model_reasoning_effort={toml_str(ctx.reasoning_effort)}"]
         argv += list(ctx.mcp_argv)

agentshim-0.9.0/agentshim/providers/codex/skills.py

@@ -0,0 +1,86 @@
+"""Codex skills: recognize a load in a shell command, and hide the user's.
+
+Codex has no skill event in ``codex exec --json``: it injects a list of
+skills into the prompt and the model loads one by reading its ``SKILL.md``
+with a shell command (``sed -n '1,240p' .../.agents/skills/<name>/SKILL.md``).
+That read is the only trace of the load in the stream, so it is inferred
+here and nowhere else.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import TYPE_CHECKING
+
+from agentshim.core.events import SkillInvoked
+
+from ._toml import toml_str
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+#: A path ending in ``skills/[<group>/...]<name>/SKILL.md``, as one shell word.
+_SKILL_FILE = re.compile(
+    r"(?<![^\s'\"=])(?P<path>(?:[^\s'\"]*/)?skills/(?:[^\s'\"/]+/)*?(?P<name>[^\s'\"/]+)/SKILL\.md)(?![^\s'\";|&)])"
+)
+
+
+def skill_reads(command: str, tool_id: str | None) -> list[SkillInvoked]:
+    """Return one ``SkillInvoked`` per ``SKILL.md`` the command names, in order."""
+    return [
+        SkillInvoked(name=match["name"], source_path=match["path"], tool_id=tool_id)
+        for match in _SKILL_FILE.finditer(command)
+    ]
+
+
+#: Codex's own bundled skills, which it re-extracts into every home.
+_SYSTEM_SKILLS = ".system"
+
+
+def user_skill_files(env: Mapping[str, str]) -> list[str]:
+    """Every user-installed ``SKILL.md`` the CLI run with *env* would offer.
+
+    Codex reads user skills from ``$CODEX_HOME/skills`` (default
+    ``~/.codex/skills``) and ``~/.agents/skills``, beside the workspace's own
+    ``.agents/skills``. ``$CODEX_HOME/skills/.system`` holds Codex's bundled
+    skills and is not the user's. Paths are listed as found and, when a
+    symlink is involved, also resolved, since either spelling may be the one
+    Codex matches against. The scan runs where agentshim runs, so a CLI in a
+    container is only covered when the container shares this home.
+    """
+    home = env.get("HOME") or os.path.expanduser("~")  # noqa: PTH111 - a str contract, not a Path
+    codex_home = env.get("CODEX_HOME") or os.path.join(home, ".codex")  # noqa: PTH118
+    roots = [os.path.join(codex_home, "skills"), os.path.join(home, ".agents", "skills")]  # noqa: PTH118
+    found: list[str] = []
+    for root in roots:
+        for directory, subdirs, files in os.walk(root, followlinks=True):
+            if directory == root and _SYSTEM_SKILLS in subdirs:
+                subdirs.remove(_SYSTEM_SKILLS)
+            subdirs.sort()
+            if "SKILL.md" in files:
+                path = os.path.join(directory, "SKILL.md")  # noqa: PTH118
+                found.append(path)
+                resolved = os.path.realpath(path)
+                if resolved != path:
+                    found.append(resolved)
+    return list(dict.fromkeys(found))
+
+
+def project_scope_overrides(env: Mapping[str, str]) -> list[str]:
+    """``--config`` flags that leave Codex only the workspace's skills.
+
+    Plugins are switched off as a feature (their skills, MCP servers and
+    apps go with them), and each user skill is disabled by path through
+    ``skills.config``. The override replaces any ``skills.config`` in the
+    user's ``config.toml``, which is user policy this scope excludes anyway.
+    """
+    entries = ", ".join(
+        f"{{path = {toml_str(path)}, enabled = false}}" for path in user_skill_files(env)
+    )
+    return [
+        "--config",
+        "features.plugins=false",
+        "--config",
+        f"skills.config=[{entries}]",
+    ]

{agentshim-0.8.0 → agentshim-0.9.0}/pyproject.toml

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

agentshim-0.8.0/agentshim/providers/codex/skills.py

@@ -1,27 +0,0 @@
-"""Recognize a Codex skill load in a shell command.
-
-Codex has no skill event in ``codex exec --json``: it injects a list of
-skills into the prompt and the model loads one by reading its ``SKILL.md``
-with a shell command (``sed -n '1,240p' .../.agents/skills/<name>/SKILL.md``).
-That read is the only trace of the load in the stream, so it is inferred
-here and nowhere else.
-"""
-
-from __future__ import annotations
-
-import re
-
-from agentshim.core.events import SkillInvoked
-
-#: A path ending in ``skills/[<group>/...]<name>/SKILL.md``, as one shell word.
-_SKILL_FILE = re.compile(
-    r"(?<![^\s'\"=])(?P<path>(?:[^\s'\"]*/)?skills/(?:[^\s'\"/]+/)*?(?P<name>[^\s'\"/]+)/SKILL\.md)(?![^\s'\";|&)])"
-)
-
-
-def skill_reads(command: str, tool_id: str | None) -> list[SkillInvoked]:
-    """Return one ``SkillInvoked`` per ``SKILL.md`` the command names, in order."""
-    return [
-        SkillInvoked(name=match["name"], source_path=match["path"], tool_id=tool_id)
-        for match in _SKILL_FILE.finditer(command)
-    ]