agentshim 0.7.0__tar.gz → 0.9.0__tar.gz

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

@@ -1,5 +1,65 @@
 # 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
+new `TurnResult` field sees no change, but an exhaustive match over
+`AgentEvent` gains two members.
+
+### Added
+
+- `SkillsDiscovered(names)` and `SkillInvoked(name, source_path, tool_id)`
+  events. `SkillInvoked` sits directly after the `ToolCall` that loaded the
+  skill.
+- `TurnResult.skills`: a `SkillSummary` (`discovered`, `invocations`,
+  `invoked`, `invocation_count`) folded from those events by `SkillTracker`,
+  which callers can also register as a handler to cover several turns.
+  `None` means unknown, never zero.
+- `ProviderProfile.skill_discovery` and `skill_invocation`, each a
+  `SkillSignal` (`NONE`, `STRUCTURED`, `INFERRED`).
+- Claude Code: discovery from the `system/init` `skills` list; a load is a
+  `Skill` tool call or a `Read` of a `SKILL.md`.
+- Codex: a load is inferred from a shell command that names a `SKILL.md`
+  under a `skills/` directory. `codex exec --json` does not list offered
+  skills, so discovery is unknown.
+- Gemini, opencode and Copilot report unknown for both.
+- `scripted_turn(..., skills_offered=[...], skills_invoked=[...])` scripts the
+  offered list (Claude) and skill loads (Claude, Codex) in each provider's own
+  format; a provider whose stream cannot carry them raises `ValueError`.
+- Recorded skill streams under `tests/fixtures/{claude,codex}/` and a live
+  e2e suite, `tests/e2e/test_skills_e2e.py`, with a positive and a negative
+  turn per provider.
+
+### Fixed
+
+- `normalize(schema, SchemaDialect.STRICT)` no longer closes an open map
+  (`additionalProperties` a schema or `true`), which silently turned
+  `dict[str, float]` into an object that can only be empty. The map is kept
+  and `dialect_problems` on the normalized schema reports it, so
+  `dialect_problems(normalize(s, d), d) == []` is the check for whether a
+  generated schema can go native.
+
 ## 0.7.0 (2026-09-27)
 
 First-class cache accounting and a static pricing table. Additive except one

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

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

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

@@ -49,6 +49,12 @@ from .core import (
     SchemaDialectError,
     SessionResumeError,
     SessionStarted,
+    SkillInvoked,
+    SkillScope,
+    SkillsDiscovered,
+    SkillSignal,
+    SkillSummary,
+    SkillTracker,
     Stderr,
     StdioMcpServer,
     StreamParser,
@@ -91,7 +97,7 @@ from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
 
-__version__ = "0.7.0"
+__version__ = "0.9.0"
 
 __all__ = [
     "AgentEvent",
@@ -153,6 +159,12 @@ __all__ = [
     "SchemaDialectError",
     "SessionResumeError",
     "SessionStarted",
+    "SkillInvoked",
+    "SkillScope",
+    "SkillSignal",
+    "SkillSummary",
+    "SkillTracker",
+    "SkillsDiscovered",
     "Stderr",
     "StdioMcpServer",
     "StreamParser",

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

@@ -23,9 +23,10 @@ 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
 from agentshim.core.turn import TurnRequest, TurnResult, coerce_request
 from agentshim.execution.executor import CommandRequest
 from agentshim.execution.host import HostCommandExecutor
@@ -113,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,
@@ -123,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:
@@ -142,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.
 
@@ -149,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
@@ -259,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)
@@ -278,8 +296,10 @@ class AgentSession:
         agent = self._agent
         handler = agent.event_handler
         resumed = self.session_id is not None
+        skills = SkillTracker(self.profile)
 
         def emit(event: AgentEvent) -> None:
+            skills.on_event(event)
             handler.on_event(event)
 
         argv = list(command.argv)
@@ -305,6 +325,7 @@ class AgentSession:
             cost_usd=parsed.cost_usd,
             duration_ms=duration_ms,
             exit_code=result.returncode,
+            skills=skills.summary(),
         )
         self.last_result = turn_result
         return turn_result

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

@@ -34,6 +34,8 @@ from .events import (
     RunFinished,
     RunStarted,
     SessionStarted,
+    SkillInvoked,
+    SkillsDiscovered,
     Stderr,
     ToolCall,
     ToolResult,
@@ -51,9 +53,17 @@ from .mcp import (
     install_config_file,
 )
 from .pricing import ModelPricing, PricingTable, cost_usd, default_pricing, price_for
-from .profile import McpMechanism, OutputSchemaStyle, ProviderProfile, SchemaDialect
+from .profile import (
+    McpMechanism,
+    OutputSchemaStyle,
+    ProviderProfile,
+    SchemaDialect,
+    SkillScope,
+    SkillSignal,
+)
 from .provider import ArgvContext, McpInstallation, ParsedTurn, Provider, StreamParser
 from .schema import compact_json, dialect_problems, materialize, normalize
+from .skills import SkillSummary, SkillTracker
 from .stream import ToolTracker, parse_json_object
 from .turn import OutputSchema, TurnRequest, TurnResult
 from .usage import ProviderUsage, TokenUsage, TokenWeights, normalized_usage
@@ -100,6 +110,12 @@ __all__ = [
     "SchemaDialectError",
     "SessionResumeError",
     "SessionStarted",
+    "SkillInvoked",
+    "SkillScope",
+    "SkillSignal",
+    "SkillSummary",
+    "SkillTracker",
+    "SkillsDiscovered",
     "Stderr",
     "StdioMcpServer",
     "StreamParser",

{agentshim-0.7.0 → agentshim-0.9.0}/agentshim/core/events.py

@@ -74,6 +74,34 @@ class ToolResult:
     duration_s: float | None
 
 
+@dataclass(frozen=True)
+class SkillsDiscovered:
+    """The provider listed the skills it offers this session.
+
+    ``names`` are the skill names as the provider reports them (a plugin
+    skill may carry a ``plugin:`` prefix). Only emitted by a provider whose
+    profile declares ``skill_discovery`` other than ``SkillSignal.NONE``, and
+    only when its stream actually carried the list.
+    """
+
+    names: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class SkillInvoked:
+    """The agent loaded a skill's instructions.
+
+    Emitted at the point in the stream where the load happened, directly
+    after the ``ToolCall`` that performed it; ``tool_id`` names that call.
+    ``source_path`` is the skill file or directory when the stream reveals
+    it, and ``None`` otherwise.
+    """
+
+    name: str
+    source_path: str | None = None
+    tool_id: str | None = None
+
+
 @dataclass(frozen=True)
 class UsageReport:
     """Provider accounting for the turn so far."""
@@ -119,6 +147,8 @@ AgentEvent = (
     | Reasoning
     | ToolCall
     | ToolResult
+    | SkillsDiscovered
+    | SkillInvoked
     | UsageReport
     | Lifecycle
     | Stderr
@@ -351,6 +381,8 @@ class ConsoleEventHandler:
         """
         if isinstance(event, Stderr):
             self._line(f"[stderr] {event.text.rstrip()}")
+        elif isinstance(event, SkillInvoked):
+            self._line(self._paint(f"[Skill] {event.name}", self._BLUE))
         elif isinstance(event, ProviderError):
             self._line(f"[error] {event.message}")
         elif isinstance(event, Lifecycle) and self._show_lifecycle:

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

@@ -46,6 +46,37 @@ class SchemaDialect(Enum):
     OPEN = "open"
 
 
+class SkillSignal(Enum):
+    """How much a provider's output stream says about skills.
+
+    ``NONE``: nothing; a caller must treat skill use as unknown, never as
+    zero. ``STRUCTURED``: the CLI emits a dedicated, documented frame.
+    ``INFERRED``: agentshim derives it from tool activity (for example a
+    shell read of a skill's ``SKILL.md``), so a load by other means can be
+    missed.
+    """
+
+    NONE = "none"
+    STRUCTURED = "structured"
+    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.
 
@@ -90,3 +121,9 @@ class ProviderProfile:
     state_root_env: str | None = None
     auth_files: tuple[str, ...] = ()
     mcp_config_file: str | None = None
+    #: Whether the stream lists the skills offered (``SkillsDiscovered``).
+    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.7.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.7.0 → agentshim-0.9.0}/agentshim/core/schema.py

@@ -272,9 +272,11 @@ def normalize(schema: Mapping[str, Any], dialect: SchemaDialect) -> dict[str, An
     requires every declared property, drops ``default``, strips the annotation
     siblings of a ``$ref`` that the strict subset forbids, and removes the
     document metadata (``$schema``, ``$id``, ``title``, ``description``,
-    ``examples``) that ``dialect_problems`` reports under ``STRICT``. What
-    comes back is therefore a schema the strict subset accepts. Callers that
-    want the schema passed through untouched skip this.
+    ``examples``) that ``dialect_problems`` reports under ``STRICT``. An open
+    map (``additionalProperties`` a schema or ``true``) is kept, since closing
+    it would change what the schema accepts; so ``dialect_problems`` on the
+    normalized schema reports exactly what the dialect cannot express.
+    Callers that want the schema passed through untouched skip this.
     """
     return cast("dict[str, Any]", _normalized(copy.deepcopy(dict(schema)), dialect))
 
@@ -314,12 +316,15 @@ def _normalized(node: object, dialect: SchemaDialect) -> object:
 
 
 def _close_object(mapping: dict[str, Any], dialect: SchemaDialect) -> None:
-    additional = mapping.get("additionalProperties")
-    if additional in (None, False):
-        mapping["additionalProperties"] = False
-        return
-    if dialect is SchemaDialect.STRICT:
-        # dialect_problems already reported this; normalize does not guess.
+    """Close an object whose extra keys are merely unspecified.
+
+    An open map (``additionalProperties`` a schema or ``true``) is left open
+    in every dialect: closing it would silently turn ``dict[str, float]`` into
+    an object that can only be empty. Under ``STRICT`` it stays a problem for
+    ``dialect_problems`` to report on the normalized schema.
+    """
+    del dialect  # an open map is left open in every dialect
+    if mapping.get("additionalProperties") in (None, False):
         mapping["additionalProperties"] = False
 
 

agentshim-0.9.0/agentshim/core/skills.py

@@ -0,0 +1,75 @@
+"""What a turn did with skills, folded from its events.
+
+``SkillTracker`` is an ordinary event handler, so the summary on
+``TurnResult.skills`` and any caller that watches the stream itself read the
+same events: there is one source of truth.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .events import SkillInvoked, SkillsDiscovered
+from .profile import SkillSignal
+
+if TYPE_CHECKING:
+    from .events import AgentEvent
+    from .profile import ProviderProfile
+
+
+@dataclass(frozen=True)
+class SkillSummary:
+    """Skills a turn (or several) offered and loaded.
+
+    ``None`` means unknown: the provider's stream carries no such signal, or
+    did not carry it this time. It never means zero. An empty tuple means the
+    signal was available and nothing matched.
+    """
+
+    discovered: tuple[str, ...] | None = None
+    invocations: tuple[SkillInvoked, ...] | None = None
+
+    @property
+    def invoked(self) -> tuple[str, ...] | None:
+        """Distinct invoked skill names, in order of first use."""
+        if self.invocations is None:
+            return None
+        return tuple(dict.fromkeys(event.name for event in self.invocations))
+
+    @property
+    def invocation_count(self) -> int | None:
+        """How many loads happened, or ``None`` when unknown."""
+        if self.invocations is None:
+            return None
+        return len(self.invocations)
+
+
+class SkillTracker:
+    """Event handler that folds skill events into a ``SkillSummary``.
+
+    Feed it one turn or many; the summary covers everything it has seen.
+    """
+
+    def __init__(self, profile: ProviderProfile) -> None:
+        """Track skills for a provider with *profile*'s declared signals."""
+        self._invocation_known = profile.skill_invocation is not SkillSignal.NONE
+        self._discovered: list[str] | None = None
+        self._invocations: list[SkillInvoked] = []
+
+    def on_event(self, event: AgentEvent) -> None:
+        """Record a skill event; ignore every other event."""
+        if isinstance(event, SkillsDiscovered):
+            known = self._discovered if self._discovered is not None else []
+            known.extend(name for name in event.names if name not in known)
+            self._discovered = known
+        elif isinstance(event, SkillInvoked):
+            self._invocations.append(event)
+
+    def summary(self) -> SkillSummary:
+        """Return what has been seen so far."""
+        discovered = tuple(self._discovered) if self._discovered is not None else None
+        invocations: tuple[SkillInvoked, ...] | None = tuple(self._invocations)
+        if not self._invocation_known and not self._invocations:
+            invocations = None
+        return SkillSummary(discovered=discovered, invocations=invocations)

{agentshim-0.7.0 → agentshim-0.9.0}/agentshim/core/turn.py

@@ -2,9 +2,11 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
+from .skills import SkillSummary
+
 if TYPE_CHECKING:
     from collections.abc import Mapping, Sequence
     from pathlib import Path
@@ -62,6 +64,8 @@ class TurnResult:
     cost_usd: float | None
     duration_ms: int
     exit_code: int
+    #: Skills offered and loaded during the turn, derived from its events.
+    skills: SkillSummary = field(default_factory=SkillSummary)
 
 
 def coerce_request(request: TurnRequest | str) -> TurnRequest:

{agentshim-0.7.0 → agentshim-0.9.0}/agentshim/providers/__init__.py

@@ -36,7 +36,7 @@ if TYPE_CHECKING:
 class ScriptedLines(Protocol):
     """Builds one turn's stdout in a provider's own stream format."""
 
-    def __call__(
+    def __call__(  # noqa: PLR0913  # mirrors scripted_turn's independent knobs
         self,
         *,
         text: str = "",
@@ -44,12 +44,17 @@ class ScriptedLines(Protocol):
         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 the stdout lines of one scripted turn.
 
         ``tool_calls`` entries are ``(tool, args, output)``;
         ``structured_output`` is any JSON-serializable value the turn should
-        report as its structured payload.
+        report as its structured payload. ``skills_offered`` is the skill
+        list the provider announces and ``skills_invoked`` the skills the turn
+        loads, each scripted the way the provider shows a load; a provider
+        whose stream cannot carry either raises ``ValueError``.
         """
         ...
 

{agentshim-0.7.0 → agentshim-0.9.0}/agentshim/providers/claude/events.py

@@ -20,6 +20,8 @@ class SystemInit:
 
     session_id: str | None
     subtype: str | None
+    #: The ``skills`` list of an ``init`` frame; ``None`` when absent.
+    skills: tuple[str, ...] | None = None
 
 
 @dataclass(frozen=True)
@@ -93,6 +95,7 @@ def parse_frame(data: Mapping[str, Any]) -> ClaudeFrame | None:
         return SystemInit(
             session_id=_str_or_none(data.get("session_id")),
             subtype=_str_or_none(data.get("subtype")),
+            skills=_str_tuple_or_none(data.get("skills")),
         )
     if kind == "assistant":
         return _assistant(data)
@@ -208,6 +211,12 @@ def _str_or_none(value: object) -> str | None:
     return value if isinstance(value, str) else None
 
 
+def _str_tuple_or_none(value: object) -> tuple[str, ...] | None:
+    if not isinstance(value, list):
+        return None
+    return tuple(item for item in cast("list[object]", value) if isinstance(item, str))
+
+
 def _int_or_none(value: object) -> int | None:
     if isinstance(value, bool):
         return None

{agentshim-0.7.0 → agentshim-0.9.0}/agentshim/providers/claude/parser.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import re
 from typing import TYPE_CHECKING, Any, cast
 
 from agentshim.core.events import (
@@ -11,6 +12,8 @@ from agentshim.core.events import (
     RawOutput,
     Reasoning,
     SessionStarted,
+    SkillInvoked,
+    SkillsDiscovered,
     Stderr,
     ToolCall,
     ToolResult,
@@ -37,6 +40,15 @@ if TYPE_CHECKING:
 
 PROVIDER_NAME = "claude"
 
+#: The built-in tool through which Claude Code loads a skill.
+SKILL_TOOL = "Skill"
+
+#: The built-in tool through which Claude Code reads a file.
+READ_TOOL = "Read"
+
+#: ``.../skills/<name>/SKILL.md``: a skill's instructions, read directly.
+_SKILL_FILE = re.compile(r"/skills/(?:[^/]+/)*?(?P<name>[^/]+)/SKILL\.md$")
+
 
 def fold_usage(usage: Mapping[str, Any] | None, turns: int = 0) -> TokenUsage:
     """Normalize Claude's usage mapping to the shared token counts.
@@ -76,6 +88,30 @@ def _int(value: object) -> int:
     return 0
 
 
+def skill_invocation(
+    tool_id: str | None, tool: str, args: Mapping[str, Any] | str | None
+) -> SkillInvoked | None:
+    """Recognize a tool call that loads a skill.
+
+    Claude Code loads a skill through its ``Skill`` tool. An agent can also
+    read a ``SKILL.md`` with ``Read``, which loads the same instructions.
+    """
+    if not isinstance(args, dict):
+        return None
+    if tool == SKILL_TOOL:
+        name = args.get("skill")
+        if isinstance(name, str) and name:
+            return SkillInvoked(name=name, tool_id=tool_id)
+        return None
+    if tool == READ_TOOL:
+        path = args.get("file_path")
+        if isinstance(path, str):
+            match = _SKILL_FILE.search(path)
+            if match is not None:
+                return SkillInvoked(name=match["name"], source_path=path, tool_id=tool_id)
+    return None
+
+
 class ClaudeStreamParser:
     """Stateful parser for one Claude Code run."""
 
@@ -141,6 +177,8 @@ class ClaudeStreamParser:
             if self._session_id is None and frame.session_id:
                 self._session_id = frame.session_id
                 self._emit(SessionStarted(frame.session_id))
+            if frame.skills is not None:
+                self._emit(SkillsDiscovered(frame.skills))
         elif isinstance(frame, AssistantMessage):
             self._assistant(frame)
         elif isinstance(frame, ToolResultBlock):
@@ -170,6 +208,9 @@ class ClaudeStreamParser:
             else:
                 self._tools.start(block.tool_id, block.tool)
                 self._emit(ToolCall(block.tool_id, block.tool, block.args))
+                skill = skill_invocation(block.tool_id, block.tool, block.args)
+                if skill is not None:
+                    self._emit(skill)
 
     def _tool_result(self, frame: ToolResultBlock) -> None:
         name = self._tools.name(frame.tool_id)

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

@@ -7,7 +7,14 @@ from typing import TYPE_CHECKING, Any
 
 from agentshim.core.errors import ProviderCapabilityError, SessionResumeError
 from agentshim.core.mcp import HttpMcpServer, NoopInstallation, StdioMcpServer, install_config_file
-from agentshim.core.profile import McpMechanism, OutputSchemaStyle, ProviderProfile, SchemaDialect
+from agentshim.core.profile import (
+    McpMechanism,
+    OutputSchemaStyle,
+    ProviderProfile,
+    SchemaDialect,
+    SkillScope,
+    SkillSignal,
+)
 
 from .parser import ClaudeStreamParser
 from .sandbox import SANDBOX_ENV, SandboxConfig, build_settings, resolve_sandbox
@@ -25,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",
@@ -45,6 +63,10 @@ PROFILE = ProviderProfile(
         "ANTHROPIC_CUSTOM_HEADERS",
     ),
     skill_dirs=(".claude/skills",),
+    # ``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",
@@ -108,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.7.0 → agentshim-0.9.0}/agentshim/providers/claude/scripted.py

@@ -16,22 +16,37 @@ if TYPE_CHECKING:
     from agentshim.core.usage import TokenUsage
 
 
-def scripted_lines(
+# Mirrors scripted_turn: each option is an independent knob of the test double.
+def scripted_lines(  # noqa: PLR0913
     *,
     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]:
     """Build the stdout of one Claude turn.
 
     ``tool_calls`` entries are ``(tool, args, output)`` and become a
-    ``tool_use`` block plus the matching ``tool_result`` frame.
+    ``tool_use`` block plus the matching ``tool_result`` frame; a ``Skill``
+    call with ``{"skill": name}`` is a skill load, and each of
+    ``skills_invoked`` becomes one ahead of ``tool_calls``. ``skills_offered``
+    goes in the ``init`` frame's ``skills`` list.
     """
+    tool_calls = [
+        *(("Skill", {"skill": name}, f"Launching skill: {name}") for name in skills_invoked),
+        *tool_calls,
+    ]
     lines: list[str] = []
-    if session_id is not None:
-        lines.append(_line({"type": "system", "subtype": "init", "session_id": session_id}))
+    if session_id is not None or skills_offered is not None:
+        init: dict[str, Any] = {"type": "system", "subtype": "init"}
+        if session_id is not None:
+            init["session_id"] = session_id
+        if skills_offered is not None:
+            init["skills"] = list(skills_offered)
+        lines.append(_line(init))
 
     blocks: list[dict[str, Any]] = []
     if text:

{agentshim-0.7.0 → agentshim-0.9.0}/agentshim/providers/codex/parser.py

@@ -34,6 +34,7 @@ from .events import (
     parse_frame,
     summarize_item,
 )
+from .skills import skill_reads
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -170,6 +171,8 @@ class CodexStreamParser:
         if isinstance(item, CommandItem):
             self._tools.start(item.item_id, COMMAND_TOOL)
             self._emit(ToolCall(item.item_id, COMMAND_TOOL, {"command": item.command}))
+            for skill in skill_reads(item.command, item.item_id):
+                self._emit(skill)
         elif isinstance(item, GenericItem):
             self._tools.start(item.item_id, item.kind)
             self._emit(ToolCall(item.item_id, item.kind, dict(item.fields)))

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

@@ -13,12 +13,15 @@ from agentshim.core.profile import (
     OutputSchemaStyle,
     ProviderProfile,
     SchemaDialect,
+    SkillScope,
+    SkillSignal,
 )
 
 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
@@ -75,6 +78,10 @@ PROFILE = ProviderProfile(
     ),
     auth_env_vars=("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``).
+    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";
@@ -126,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.7.0 → agentshim-0.9.0}/agentshim/providers/codex/scripted.py

@@ -16,13 +16,16 @@ if TYPE_CHECKING:
     from agentshim.core.usage import TokenUsage
 
 
-def scripted_lines(
+# Mirrors scripted_turn: each option is an independent knob of the test double.
+def scripted_lines(  # noqa: PLR0913
     *,
     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]:
     """Build the stdout of one Codex turn.
 
@@ -38,10 +41,23 @@ def scripted_lines(
         usage: Token counts reported by ``turn.completed``.
         tool_calls: Commands to report as started-then-completed items.
         structured_output: Payload to serialize as the final message.
+        skills_offered: Must be None; the stream lists no offered skills.
+        skills_invoked: Skills to load first, each as a shell read of its
+            ``SKILL.md``.
 
     Returns:
         One newline-terminated JSON line per Codex event.
     """
+    tool_calls = [
+        *(
+            ("execute", {"command": f"cat .agents/skills/{name}/SKILL.md"}, "")
+            for name in skills_invoked
+        ),
+        *tool_calls,
+    ]
+    if skills_offered is not None:
+        msg = "Codex does not list offered skills in its stream"
+        raise ValueError(msg)
     lines: list[str] = []
     if session_id is not None:
         lines.append(_line({"type": "thread.started", "thread_id": session_id}))

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.7.0 → agentshim-0.9.0}/agentshim/providers/copilot/scripted.py

@@ -20,13 +20,16 @@ _NO_STRUCTURED_OUTPUT = (
 )
 
 
-def scripted_lines(
+# Mirrors scripted_turn: each option is an independent knob of the test double.
+def scripted_lines(  # noqa: PLR0913
     *,
     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]:
     """Build the stdout of one Copilot turn.
 
@@ -40,6 +43,8 @@ def scripted_lines(
         usage: Token counts to report in the ``assistant.usage`` frame.
         tool_calls: Tool calls to script.
         structured_output: Must be None; Copilot has no native output schema.
+        skills_offered: Must be None; the stream lists no offered skills.
+        skills_invoked: Must be empty; the stream reports no skill loads.
 
     Returns:
         The stdout lines, each a JSON object with a trailing newline.
@@ -47,6 +52,12 @@ def scripted_lines(
     Raises:
         ValueError: If ``structured_output`` is given.
     """
+    if skills_invoked:
+        msg = "Copilot reports no skill loads in its stream"
+        raise ValueError(msg)
+    if skills_offered is not None:
+        msg = "Copilot does not list offered skills in its stream"
+        raise ValueError(msg)
     if structured_output is not None:
         raise ValueError(_NO_STRUCTURED_OUTPUT)
 

{agentshim-0.7.0 → agentshim-0.9.0}/agentshim/providers/gemini/scripted.py

@@ -25,13 +25,16 @@ _NO_STRUCTURED_OUTPUT = (
 )
 
 
-def scripted_lines(
+# Mirrors scripted_turn: each option is an independent knob of the test double.
+def scripted_lines(  # noqa: PLR0913
     *,
     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]:
     """Build the stdout of one Gemini turn.
 
@@ -45,6 +48,8 @@ def scripted_lines(
         usage: Token counts to report in the terminal ``result`` frame.
         tool_calls: Tool calls to script.
         structured_output: Must be None; Gemini has no native output schema.
+        skills_offered: Must be None; the stream lists no offered skills.
+        skills_invoked: Must be empty; the stream reports no skill loads.
 
     Returns:
         The stdout lines, each a JSON object with a trailing newline.
@@ -52,6 +57,12 @@ def scripted_lines(
     Raises:
         ValueError: If ``structured_output`` is given.
     """
+    if skills_invoked:
+        msg = "Gemini reports no skill loads in its stream"
+        raise ValueError(msg)
+    if skills_offered is not None:
+        msg = "Gemini does not list offered skills in its stream"
+        raise ValueError(msg)
     if structured_output is not None:
         raise ValueError(_NO_STRUCTURED_OUTPUT)
 

{agentshim-0.7.0 → agentshim-0.9.0}/agentshim/providers/opencode/scripted.py

@@ -25,13 +25,16 @@ _NO_STRUCTURED_OUTPUT = (
 )
 
 
-def scripted_lines(
+# Mirrors scripted_turn: each option is an independent knob of the test double.
+def scripted_lines(  # noqa: PLR0913
     *,
     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]:
     """Build the stdout of one opencode turn.
 
@@ -45,6 +48,8 @@ def scripted_lines(
         usage: Token counts to report in the closing ``step_finish`` frame.
         tool_calls: Tool calls to script.
         structured_output: Must be None; opencode has no native output schema.
+        skills_offered: Must be None; the stream lists no offered skills.
+        skills_invoked: Must be empty; the stream reports no skill loads.
 
     Returns:
         The stdout lines, each a JSON object with a trailing newline.
@@ -52,6 +57,12 @@ def scripted_lines(
     Raises:
         ValueError: If ``structured_output`` is given.
     """
+    if skills_invoked:
+        msg = "opencode reports no skill loads in its stream"
+        raise ValueError(msg)
+    if skills_offered is not None:
+        msg = "opencode does not list offered skills in its stream"
+        raise ValueError(msg)
     if structured_output is not None:
         raise ValueError(_NO_STRUCTURED_OUTPUT)
 

{agentshim-0.7.0 → agentshim-0.9.0}/agentshim/testing/__init__.py

@@ -160,14 +160,25 @@ def scripted_turn(  # noqa: PLR0913
     tool_calls: Sequence[tuple[str, Mapping[str, Any], str]] = (),
     structured_output: object | None = None,
     returncode: int = 0,
+    skills_offered: Sequence[str] | None = None,
+    skills_invoked: Sequence[str] = (),
 ) -> FakeRun:
-    """Build a ``FakeRun`` whose stdout is *provider*'s real stream format."""
+    """Build a ``FakeRun`` whose stdout is *provider*'s real stream format.
+
+    ``skills_invoked`` scripts one load per name, before ``tool_calls``, the
+    way *provider* shows a load, so the turn reports a ``SkillInvoked`` each.
+    ``skills_offered`` scripts the offered list. Either raises ``ValueError``
+    on a provider whose stream cannot carry it (the matching
+    ``profile.skill_*`` signal is ``NONE``).
+    """
     lines = get_scripted_lines(provider)(
         text=text,
         session_id=session_id,
         usage=usage,
         tool_calls=tool_calls,
         structured_output=structured_output,
+        skills_offered=skills_offered,
+        skills_invoked=skills_invoked,
     )
     return FakeRun(stdout=lines, returncode=returncode)
 

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

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