arcgentic 0.2.2a3__py3-none-any.whl

arcgentic/__init__.py

@@ -0,0 +1,5 @@
+"""arcgentic — agentic harness for rigorous round-driven development."""
+
+from __future__ import annotations
+
+__version__ = "0.2.2-alpha.3"

arcgentic/adapters/__init__.py

@@ -0,0 +1,77 @@
+"""IDE adapter auto-detection.
+
+`detect_adapter()` inspects environment variables, filesystem markers, and
+binary availability to select the appropriate adapter for the current host.
+Falls back to InlineAdapter if no LLM host can be confidently identified.
+
+Detection rules (each: env-var checks use Python truthiness — empty-string
+env-var values fall through, which is the intended behavior since empty-string
+markers are semantically equivalent to unset):
+  1. Claude Code  — CLAUDE_CODE_SESSION (non-empty) OR ~/.claude/skills dir exists (home-relative)
+  2. Cursor       — CURSOR_SESSION (non-empty) OR .cursor/rules dir exists (CWD-relative)
+  3. VSCode+Codex — VSCODE_PID (non-empty) AND `codex` binary on PATH
+  4. Codex CLI    — CODEX_SESSION (non-empty) OR `codex` binary on PATH
+  5. Inline       — fallback when no LLM host can be identified
+
+Public API:
+  detect_adapter() -> IDEAdapter
+  IDEAdapter (re-export from .base for convenience)
+  AgentDispatchResult (re-export from .base)
+
+Spec reference: docs/plans/2026-05-13-arcgentic-v0.2.0-spec.md § 3.6
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from shutil import which
+
+from .base import AgentDispatchResult, IDEAdapter
+
+__all__ = ["detect_adapter", "IDEAdapter", "AgentDispatchResult"]
+
+
+def detect_adapter() -> IDEAdapter:
+    """Return the IDEAdapter best matching the current runtime environment.
+
+    Falls back to InlineAdapter if no LLM host can be detected. Callers should
+    NOT assume the returned adapter can dispatch agents (InlineAdapter can't
+    actually dispatch — it's a degraded fallback for dry-run / headless use).
+    """
+    # 1. Claude Code
+    if os.environ.get("CLAUDE_CODE_SESSION") or _has_dir("~/.claude/skills"):
+        from .claude_code import ClaudeCodeAdapter
+        return ClaudeCodeAdapter()
+
+    # rule 2 — Cursor (.cursor/rules is project-local, CWD-relative;
+    # detect_adapter() picks up the marker only when called from project root)
+    if os.environ.get("CURSOR_SESSION") or _has_dir(".cursor/rules"):
+        from .cursor import CursorAdapter
+        return CursorAdapter()
+
+    # 3. VSCode + Codex (must have BOTH a VSCode env marker AND codex binary)
+    if os.environ.get("VSCODE_PID") and which("codex"):
+        from .vscode_codex import VSCodeCodexAdapter
+        return VSCodeCodexAdapter()
+
+    # 4. Codex CLI standalone (CODEX_SESSION env, OR codex binary without VSCode)
+    if os.environ.get("CODEX_SESSION") or which("codex"):
+        from .codex_cli import CodexCLIAdapter
+        return CodexCLIAdapter()
+
+    # 5. Fallback
+    from .inline import InlineAdapter
+    return InlineAdapter()
+
+
+def _has_dir(path: str) -> bool:
+    """Return True if `path` is a directory (after ~-expansion).
+
+    Paths starting with `~` are home-relative (expand to $HOME).
+    Other paths are interpreted relative to the current working directory.
+    Used by detect_adapter() for both home-scoped markers (e.g. ~/.claude/skills,
+    Claude Code installation) and project-scoped markers (e.g. .cursor/rules,
+    Cursor project rules).
+    """
+    return Path(path).expanduser().is_dir()

arcgentic/adapters/_local_env.py

@@ -0,0 +1,125 @@
+"""Shared local-environment helpers for IDEAdapter implementations.
+
+These functions implement filesystem / shell / git operations that are identical
+across all non-canonical IDE adapters (Cursor / VSCode-Codex / Codex CLI / Inline).
+The canonical ClaudeCodeAdapter inlines these directly; a future cleanup task may
+unify it with this module.
+
+These are module-level functions (NOT a class) because they have no state — each
+call is a fresh subprocess or filesystem op. Adapters call them as
+`_local_env.read_file(path)` etc.
+
+Spec reference: docs/plans/2026-05-13-arcgentic-v0.2.0-spec.md § 3.3–§ 3.5
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def read_file(path: str) -> str:
+    """Read a file and return its text content (utf-8)."""
+    return Path(path).read_text(encoding="utf-8")
+
+
+def write_file(path: str, content: str) -> None:
+    """Write `content` to `path` (utf-8); creates or overwrites."""
+    Path(path).write_text(content, encoding="utf-8")
+
+
+def edit_file(path: str, old: str, new: str) -> None:
+    """Replace exactly one occurrence of `old` with `new`.
+
+    Raises ValueError on zero or multi-match (identical contract to
+    ClaudeCodeAdapter.edit_file per spec § 3 IDEAdapter Protocol).
+    """
+    p = Path(path)
+    text = p.read_text(encoding="utf-8")
+    count = text.count(old)
+    if count == 0:
+        raise ValueError(f"edit_file: `old` not found in {path}")
+    if count > 1:
+        raise ValueError(f"edit_file: `old` appears {count} times in {path} (ambiguous)")
+    p.write_text(text.replace(old, new, 1), encoding="utf-8")
+
+
+def shell(command: str, timeout_seconds: int = 120) -> tuple[str, int]:
+    """Run a shell command; return (stdout, exit_code).
+
+    On TimeoutExpired returns ('', 124) — same POSIX timeout convention as
+    ClaudeCodeAdapter.shell.
+    """
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+            check=False,
+        )
+        return result.stdout, result.returncode
+    except subprocess.TimeoutExpired:
+        return "", 124
+
+
+def _run_git(args: list[str], timeout_seconds: int = 60) -> tuple[str, str, int]:
+    """Run `git <args>` via list-form subprocess (no shell=True).
+
+    Returns (stdout, stderr, exit_code). Used by git_diff_staged / git_commit
+    which need stderr for error diagnostics — shell() can't return stderr
+    without breaking the IDEAdapter Protocol's tuple[str, int] signature.
+
+    Underscore-prefix signals this is an internal helper; callers should use
+    git_diff_staged() and git_commit() (the public surface).
+    """
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+            check=False,
+        )
+        return result.stdout, result.stderr, result.returncode
+    except subprocess.TimeoutExpired:
+        return "", f"git {args[0] if args else ''} timed out", 124
+
+
+def git_diff_staged() -> str:
+    """Return the output of `git diff --staged`.
+
+    Raises RuntimeError if git exits non-zero (e.g., not in a git repo).
+    """
+    stdout, stderr, code = _run_git(["diff", "--staged"])
+    if code != 0:
+        raise RuntimeError(f"git diff --staged failed (exit {code}): {stderr.strip()}")
+    return stdout
+
+
+def git_commit(message: str, files: list[str] | None = None) -> str:
+    """Stage `files` (if provided) then commit; return the new SHA.
+
+    If `files` is None, commits whatever is already in the index.
+    Does NOT use --no-verify / --no-gpg-sign / --amend per Protocol contract.
+    """
+    if files is not None:
+        for f in files:
+            _, stderr, code = _run_git(["add", "--", f])
+            if code != 0:
+                raise RuntimeError(f"git add {f} failed (exit {code}): {stderr.strip()}")
+
+    _, stderr, code = _run_git(["commit", "-m", message])
+    if code != 0:
+        raise RuntimeError(f"git commit failed (exit {code}): {stderr.strip()}")
+
+    stdout, stderr, code = _run_git(["rev-parse", "HEAD"])
+    if code != 0:
+        raise RuntimeError(f"git rev-parse HEAD failed (exit {code}): {stderr.strip()}")
+    return stdout.strip()
+
+
+def shquote(s: str) -> str:
+    """POSIX single-quote escape for safe shell=True interpolation."""
+    return "'" + s.replace("'", "'\\''") + "'"

arcgentic/adapters/base.py

@@ -0,0 +1,108 @@
+"""IDE Adapter Protocol — the abstraction surface arcgentic skills/CLI use to talk
+to whatever AI agent platform is hosting them (Claude Code / Cursor / VSCode-Codex /
+Codex CLI / inline fallback).
+
+Adding a new platform = implementing this Protocol; arcgentic skills/CLI then work
+unchanged.
+
+Anti-contamination invariant (spec § 1.5): adapter methods MUST NOT inject
+`tools=` or `tool_choice=` at the agent level. Those belong one layer down
+in the LLM-client layer.
+
+Spec reference: docs/plans/2026-05-13-arcgentic-v0.2.0-spec.md § 3.1
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class AgentDispatchResult:
+    """Result of dispatching a sub-agent through an IDE adapter.
+
+    `output`        : the agent's stdout / response text
+    `exit_code`     : 0 = success; non-zero = failure
+    `duration_ms`   : wall-clock ms from dispatch to result
+    `agent_type`    : the agent_name that was dispatched (echoed back for trace)
+    `error`         : optional error message (None on success)
+    """
+
+    output: str
+    exit_code: int
+    duration_ms: int
+    agent_type: str
+    error: str | None = None
+
+
+@runtime_checkable
+class IDEAdapter(Protocol):
+    """Adapter for an AI IDE/agent platform.
+
+    Each platform (claude-code / cursor / vscode-codex / codex-cli / inline)
+    implements this Protocol. arcgentic skills + CLI invoke platform-agnostic
+    methods; the adapter translates to platform-specific tool calls.
+
+    Anti-contamination invariant (spec § 1.5): adapter methods MUST NOT inject
+    `tools=` or `tool_choice=` at the agent level. Those belong one layer down
+    in the LLM-client layer.
+    """
+
+    platform_name: str  # "claude-code" / "cursor" / "vscode-codex" / "codex-cli" / "inline"
+
+    def dispatch_agent(
+        self,
+        agent_name: str,
+        prompt: str,
+        timeout_seconds: int = 600,
+        isolation: Literal["worktree"] | None = None,
+    ) -> AgentDispatchResult:
+        """Dispatch a sub-agent.
+
+        `agent_name` maps to a markdown file at agents/<name>.md.
+        `prompt` is the full self-contained brief; agent has zero session context.
+        Returns the agent's response wrapped in AgentDispatchResult.
+        """
+        ...
+
+    def invoke_skill(self, skill_name: str, args: str = "") -> str:
+        """Invoke an arcgentic skill in-process.
+
+        `skill_name` maps to a markdown file at skills/<name>/SKILL.md.
+        `args` is the optional argument string for the skill.
+        Returns the skill's textual output.
+        """
+        ...
+
+    def read_file(self, path: str) -> str: ...
+
+    def write_file(self, path: str, content: str) -> None: ...
+
+    def edit_file(self, path: str, old: str, new: str) -> None:
+        """Replace exactly one occurrence of `old` with `new` in file at `path`.
+
+        Match is exact-string (no regex). Implementations MUST raise an error if
+        `old` is not found, or if `old` appears more than once (ambiguous match).
+        For multi-occurrence replacement, callers should invoke `edit_file` multiple
+        times with disambiguating context, or use a higher-level batch API.
+        """
+        ...
+
+    def shell(self, command: str, timeout_seconds: int = 120) -> tuple[str, int]:
+        """Run a shell command; return (output, exit_code)."""
+        ...
+
+    def git_diff_staged(self) -> str: ...
+
+    def git_commit(self, message: str, files: list[str] | None = None) -> str:
+        """Commit staged changes; return the commit SHA.
+
+        If `files` is provided (non-None), stage those files first via `git add <file>...`
+        then commit. If `files` is None, commit whatever is currently in the index without
+        staging anything (caller has already staged).
+
+        Implementations must NOT use `--no-verify`, `--no-gpg-sign`, or `--amend` unless
+        the adapter explicitly documents otherwise.
+        """
+        ...

arcgentic/adapters/claude_code.py

@@ -0,0 +1,223 @@
+"""Claude Code adapter — canonical reference IDEAdapter implementation.
+
+When arcgentic skills/CLI run inside (or alongside) a Claude Code installation,
+this adapter is what `detect_adapter()` selects.
+
+Implementation strategy:
+- `dispatch_agent` + `invoke_skill`: subprocess `claude -p "<wrapped prompt>"` —
+  each dispatch is a fresh, stateless Claude Code session (matches spec § 5
+  stateless-agent principle). NOTE: consumes Claude Code subscription tokens per
+  dispatch; documented cost trade-off.
+- `read_file` / `write_file` / `edit_file`: Python filesystem APIs (no LLM
+  mediation needed; spec § 3.2 says these "wrap" Read/Write/Edit but at the
+  Python layer that means direct filesystem access).
+- `shell`: subprocess.run with shell=True; timeout enforced.
+- `git_diff_staged` / `git_commit`: subprocess git invocations.
+
+Anti-contamination invariant (spec § 1.5) is preserved: dispatch_agent does NOT
+inject tools= or tool_choice=; the prompt string is the only payload sent
+to the spawned Claude Code session.
+
+Spec reference: docs/plans/2026-05-13-arcgentic-v0.2.0-spec.md § 3.2
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Literal
+
+from .base import AgentDispatchResult
+
+
+class ClaudeCodeAdapter:
+    """Concrete IDEAdapter for Claude Code."""
+
+    platform_name = "claude-code"
+
+    def __init__(self, claude_binary: str = "claude") -> None:
+        """Create a ClaudeCodeAdapter.
+
+        `claude_binary`: name (or path) of the `claude` CLI executable. Default
+        "claude" assumes it's on PATH. Tests can inject a stub binary path.
+        """
+        self._claude_binary = claude_binary
+
+    # ── LLM-mediated methods ──────────────────────────────────────────────
+
+    def dispatch_agent(
+        self,
+        agent_name: str,
+        prompt: str,
+        timeout_seconds: int = 600,
+        isolation: Literal["worktree"] | None = None,
+    ) -> AgentDispatchResult:
+        """Spawn `claude -p "<wrapped>"` with the agent brief.
+
+        The wrapped prompt prefixes the brief with "Acting as the {agent_name}
+        agent:\\n\\n" to nudge the spawned Claude Code session into the right role.
+        Each dispatch is a fresh session; the spawned process inherits no context
+        from the calling session.
+
+        `isolation="worktree"` is currently a NO-OP for Claude Code (the spawned
+        session inherits the caller's working directory). Future versions may wrap
+        the call in `git worktree add` and clean up after; reserved for forward
+        compatibility.
+        """
+        if not self._has_claude_binary():
+            return AgentDispatchResult(
+                output="",
+                exit_code=127,
+                duration_ms=0,
+                agent_type=agent_name,
+                error=f"`{self._claude_binary}` not found on PATH",
+            )
+
+        wrapped = f"Acting as the {agent_name} agent:\n\n{prompt}"
+        start = time.monotonic()
+        try:
+            result = subprocess.run(
+                [self._claude_binary, "-p", wrapped],
+                capture_output=True,
+                text=True,
+                timeout=timeout_seconds,
+                check=False,
+            )
+            duration_ms = int((time.monotonic() - start) * 1000)
+            error = result.stderr.strip() if result.returncode != 0 else None
+            return AgentDispatchResult(
+                output=result.stdout,
+                exit_code=result.returncode,
+                duration_ms=duration_ms,
+                agent_type=agent_name,
+                error=error,
+            )
+        except subprocess.TimeoutExpired:
+            duration_ms = int((time.monotonic() - start) * 1000)
+            return AgentDispatchResult(
+                output="",
+                exit_code=124,  # POSIX timeout convention
+                duration_ms=duration_ms,
+                agent_type=agent_name,
+                error=f"timeout after {timeout_seconds}s",
+            )
+
+    def invoke_skill(self, skill_name: str, args: str = "") -> str:
+        """Invoke a skill by issuing the slash-command via `claude -p`.
+
+        Wraps as "Invoke /{skill_name} {args}" — Claude Code interprets this as a
+        skill invocation. Returns the stdout of the spawned session.
+        """
+        if not self._has_claude_binary():
+            raise RuntimeError(f"`{self._claude_binary}` not found on PATH")
+
+        prompt = f"Invoke /{skill_name} {args}".strip()
+        try:
+            result = subprocess.run(
+                [self._claude_binary, "-p", prompt],
+                capture_output=True,
+                text=True,
+                timeout=600,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            raise RuntimeError(f"/{skill_name} timed out after 600s") from None
+
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"`/{skill_name}` exited {result.returncode}: {result.stderr.strip()}"
+            )
+        return result.stdout
+
+    # ── Filesystem (no LLM mediation) ─────────────────────────────────────
+
+    def read_file(self, path: str) -> str:
+        return Path(path).read_text(encoding="utf-8")
+
+    def write_file(self, path: str, content: str) -> None:
+        Path(path).write_text(content, encoding="utf-8")
+
+    def edit_file(self, path: str, old: str, new: str) -> None:
+        p = Path(path)
+        text = p.read_text(encoding="utf-8")
+        count = text.count(old)
+        if count == 0:
+            raise ValueError(f"edit_file: `old` not found in {path}")
+        if count > 1:
+            raise ValueError(
+                f"edit_file: `old` appears {count} times in {path} (ambiguous)"
+            )
+        p.write_text(text.replace(old, new, 1), encoding="utf-8")
+
+    # ── Shell + git ────────────────────────────────────────────────────────
+
+    def shell(self, command: str, timeout_seconds: int = 120) -> tuple[str, int]:
+        try:
+            result = subprocess.run(
+                command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=timeout_seconds,
+                check=False,
+            )
+            return result.stdout, result.returncode
+        except subprocess.TimeoutExpired:
+            return "", 124
+
+    def git_diff_staged(self) -> str:
+        stdout, stderr, code = self._run_git(["diff", "--staged"])
+        if code != 0:
+            raise RuntimeError(f"git diff --staged failed (exit {code}): {stderr.strip()}")
+        return stdout
+
+    def git_commit(self, message: str, files: list[str] | None = None) -> str:
+        if files is not None:
+            # Stage explicitly listed files first.
+            for f in files:
+                _, stderr, code = self._run_git(["add", "--", f])
+                if code != 0:
+                    raise RuntimeError(f"git add {f} failed (exit {code}): {stderr.strip()}")
+
+        # Commit using -m; avoid --no-verify / --no-gpg-sign / --amend per Protocol contract.
+        _, stderr, code = self._run_git(["commit", "-m", message])
+        if code != 0:
+            raise RuntimeError(f"git commit failed (exit {code}): {stderr.strip()}")
+
+        # Return the new commit SHA.
+        stdout, stderr, code = self._run_git(["rev-parse", "HEAD"])
+        if code != 0:
+            raise RuntimeError(f"git rev-parse HEAD failed (exit {code}): {stderr.strip()}")
+        return stdout.strip()
+
+    # ── Internals ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _run_git(args: list[str], timeout_seconds: int = 60) -> tuple[str, str, int]:
+        """Run `git <args>` via list-form subprocess (no shell).
+
+        Returns (stdout, stderr, exit_code). Used by git-specific adapter methods
+        that need stderr surfaced for error diagnostics. shell() can't return
+        stderr without breaking the IDEAdapter Protocol's tuple[str, int] contract.
+        """
+        try:
+            result = subprocess.run(
+                ["git", *args],
+                capture_output=True,
+                text=True,
+                timeout=timeout_seconds,
+                check=False,
+            )
+            return result.stdout, result.stderr, result.returncode
+        except subprocess.TimeoutExpired:
+            return "", f"git {args[0] if args else ''} timed out", 124
+
+    def _has_claude_binary(self) -> bool:
+        return shutil.which(self._claude_binary) is not None
+
+    @staticmethod
+    def _shquote(s: str) -> str:
+        """Minimal shell-quoting (single-quote escape) for safe `shell=True` use."""
+        return "'" + s.replace("'", "'\\''") + "'"

arcgentic/adapters/codex_cli.py

@@ -0,0 +1,145 @@
+"""Codex CLI adapter (standalone).
+
+When arcgentic skills/CLI run outside VSCode but with the standalone Codex CLI
+installed, this adapter is what `detect_adapter()` selects. It is structurally
+identical to VSCodeCodexAdapter — both subprocess to the same `codex` binary
+with the same `agent dispatch` / `skill invoke` wire format. The distinction is
+purely contextual (which environment triggered the adapter selection).
+
+Wire format: `codex agent dispatch <agent_name> <prompt>` for agents,
+`codex skill invoke <skill_name> <args>` for skills.
+
+The separate class (and separate file) is intentional — adapter-per-platform
+design per spec § 3.5. Future v0.3 may unify common Codex-based logic into a
+shared base, but for P0 we keep them explicit and symmetric.
+
+Filesystem / shell / git methods delegate to _local_env shared helpers.
+
+Spec reference: docs/plans/2026-05-13-arcgentic-v0.2.0-spec.md § 3.5
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import time
+from typing import Literal
+
+from . import _local_env
+from .base import AgentDispatchResult
+
+
+class CodexCLIAdapter:
+    """Concrete IDEAdapter for standalone Codex CLI."""
+
+    platform_name = "codex-cli"
+
+    def __init__(self, codex_binary: str = "codex") -> None:
+        """Create a CodexCLIAdapter.
+
+        `codex_binary`: name (or path) of the codex CLI executable.
+        Default "codex" assumes it's on PATH. Tests can inject a stub.
+        """
+        self._codex_binary = codex_binary
+
+    # ── LLM-mediated methods ──────────────────────────────────────────────
+
+    def dispatch_agent(
+        self,
+        agent_name: str,
+        prompt: str,
+        timeout_seconds: int = 600,
+        isolation: Literal["worktree"] | None = None,
+    ) -> AgentDispatchResult:
+        """Dispatch a sub-agent via `codex agent dispatch <name> <prompt>`.
+
+        If codex binary is not on PATH, returns exit_code=127 with an error.
+        `isolation` is accepted for API symmetry but has no effect.
+        """
+        if not shutil.which(self._codex_binary):
+            return AgentDispatchResult(
+                output="",
+                exit_code=127,
+                duration_ms=0,
+                agent_type=agent_name,
+                error=f"`{self._codex_binary}` not found on PATH",
+            )
+
+        start = time.monotonic()
+        try:
+            result = subprocess.run(
+                [self._codex_binary, "agent", "dispatch", agent_name, prompt],
+                capture_output=True,
+                text=True,
+                timeout=timeout_seconds,
+                check=False,
+            )
+            duration_ms = int((time.monotonic() - start) * 1000)
+            error = result.stderr.strip() if result.returncode != 0 else None
+            return AgentDispatchResult(
+                output=result.stdout,
+                exit_code=result.returncode,
+                duration_ms=duration_ms,
+                agent_type=agent_name,
+                error=error,
+            )
+        except subprocess.TimeoutExpired:
+            duration_ms = int((time.monotonic() - start) * 1000)
+            return AgentDispatchResult(
+                output="",
+                exit_code=124,
+                duration_ms=duration_ms,
+                agent_type=agent_name,
+                error=f"timeout after {timeout_seconds}s",
+            )
+
+    def invoke_skill(self, skill_name: str, args: str = "") -> str:
+        """Invoke a skill via `codex skill invoke <skill_name> [<args>]`.
+
+        Raises RuntimeError if codex is not on PATH, exits non-zero, or times out.
+        When `args` is empty, it is omitted from the subprocess argv entirely —
+        passing "" as a positional arg is ambiguous for the codex CLI.
+        """
+        if not shutil.which(self._codex_binary):
+            raise RuntimeError(f"`{self._codex_binary}` not found on PATH")
+
+        cmd = [self._codex_binary, "skill", "invoke", skill_name]
+        if args:  # only append args if non-empty
+            cmd.append(args)
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=600,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            raise RuntimeError(f"/{skill_name} timed out after 600s") from None
+
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"`/{skill_name}` exited {result.returncode}: {result.stderr.strip()}"
+            )
+        return result.stdout
+
+    # ── Filesystem / shell / git via shared helpers ────────────────────────
+
+    def read_file(self, path: str) -> str:
+        return _local_env.read_file(path)
+
+    def write_file(self, path: str, content: str) -> None:
+        _local_env.write_file(path, content)
+
+    def edit_file(self, path: str, old: str, new: str) -> None:
+        _local_env.edit_file(path, old, new)
+
+    def shell(self, command: str, timeout_seconds: int = 120) -> tuple[str, int]:
+        return _local_env.shell(command, timeout_seconds)
+
+    def git_diff_staged(self) -> str:
+        return _local_env.git_diff_staged()
+
+    def git_commit(self, message: str, files: list[str] | None = None) -> str:
+        return _local_env.git_commit(message, files)