runspec-claude 0.1.0__tar.gz

runspec_claude-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_claude-0.1.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# runspec-claude Changelog
+
+## [0.1.0] — 2026-06-22
+
+Initial release.
+
+One runnable, `claude-run`, that drives the **Claude Code CLI** (`claude`)
+headlessly so you can use Claude — and let the runspec-console agent (itself
+Claude) delegate to Claude — as a runspec tool. Four verbs (subcommands) mirror
+the way you talk to Claude in a chat app:
+
+- **`claude-run ask "<prompt>"`** — start a fresh headless turn / session.
+- **`claude-run continue "<prompt>"`** — continue the most recent session in this
+  directory (`claude --continue`).
+- **`claude-run resume --session <id> "<prompt>"`** — continue a specific prior
+  session by id (`claude --resume`).
+- **`claude-run sessions`** — list recent sessions you can resume (read-only).
+
+Each verb shells out to `claude -p … --output-format json` and returns the
+structured result: `result` text, `session_id`, `num_turns`, `total_cost_usd`,
+`is_error`, and the full `raw` payload. The returned `session_id` lets a caller
+(or the console agent) resume the same delegated worker on a later turn — the
+"drive yourself across turns" loop with one tool.
+
+**MCP surface.** `runspec serve` flattens the runnable into one leaf tool per
+verb — `claude-run_ask`, `claude-run_continue`, `claude-run_resume`,
+`claude-run_sessions` — so the console agent sees four clearly-named tools while
+the package stays a single installable entry point. Each verb tool also carries
+the inherited global args (requires `runspec >= 0.44.0`), so an operator or the
+agent can set `permission-mode` / `model` / etc. per call — still behind the
+`confirm` gate.
+
+**Safe-by-default, operator-governed.** Every action verb is
+`autonomy = "confirm"` (a human approves each delegation); `sessions` is
+`autonomous`. The headless run defaults to `--permission-mode default` (it can
+read and plan but blocks on edits/commands) with `--max-turns 12`. The delegated
+run's power — `permission-mode`, `model`, working directory, `allowed-tools`,
+`append-system-prompt`, `bare` — is set through global args (operator-controlled,
+inherited by every verb), not by the autonomous agent: the agent's tools take a
+prompt (and `session`/`limit`); a human or the run form chooses how much the
+nested agent may do. Opt up explicitly, e.g.
+`claude-run --permission-mode acceptEdits ask "…"`.
+
+**Session listing** reads Claude Code's transcript store
+(`~/.claude/projects/<encoded-cwd>/<session-id>.jsonl`, `CLAUDE_CONFIG_DIR`
+honoured). The per-line schema is undocumented, so titles are best-effort
+(sniffed from the first user message) and the lister degrades gracefully — an
+absent directory yields an empty list.
+
+**Entry point** is deliberately named `claude-run`, not `claude`, so installing
+this package never shadows the real Claude Code CLI binary.
+
+**Public Python API** for wrapper packages that want to bake in corporate
+defaults (a fixed model, allowlist, or working directory): `run_claude`,
+`list_sessions`, `encode_project_dir`, `ClaudeError`, `ClaudeNotFoundError`.
+Every function takes plain parameters and raises typed errors — the same
+core/wrapper split used by `runspec-jsm` / `runspec-logops`.
+
+**Requirements.** The `claude` CLI must be installed on the host where the
+runnable runs (it is invoked over `subprocess`). Zero extra runtime
+dependencies beyond `runspec`.

runspec_claude-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: runspec-claude
+Version: 0.1.0
+Summary: Drive the Claude Code CLI (`claude`) headlessly as a runspec runnable
+Requires-Python: >=3.10
+Requires-Dist: runspec>=0.44.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

runspec_claude-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-claude"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Drive the Claude Code CLI (`claude`) headlessly as a runspec runnable"
+dependencies = [
+    # 0.44.0 surfaces inherited global args (model, permission-mode, …) on each
+    # leaf subcommand's MCP tool, so the console agent can set them per call.
+    "runspec>=0.44.0",
+]
+
+[project.scripts]
+# Entry point name MUST match the runnable name. Deliberately `claude-run`, not
+# `claude`, so installing this never shadows the real Claude Code CLI binary.
+claude-run = "runspec_claude.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_claude-0.1.0/runspec_claude/__init__.py

@@ -0,0 +1,24 @@
+"""runspec-claude — drive the Claude Code CLI (`claude`) headlessly from runspec.
+
+Public API (importable for a private wrapper package that bakes in defaults):
+
+    from runspec_claude import run_claude, list_sessions, ClaudeError
+"""
+
+from __future__ import annotations
+
+from .runner import (
+    ClaudeError,
+    ClaudeNotFoundError,
+    encode_project_dir,
+    list_sessions,
+    run_claude,
+)
+
+__all__ = [
+    "run_claude",
+    "list_sessions",
+    "encode_project_dir",
+    "ClaudeError",
+    "ClaudeNotFoundError",
+]

runspec_claude-0.1.0/runspec_claude/cli.py

@@ -0,0 +1,82 @@
+"""cli.py — the `claude-run` entry point.
+
+One binary, four verbs. ``rs.parse("claude-run")`` resolves the subcommand and
+the (globals + per-command) args; we dispatch on ``spec.runspec_command`` and
+delegate the actual work to :mod:`runspec_claude.runner`.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+import runspec as rs
+
+from .runner import ClaudeError, ClaudeNotFoundError, list_sessions, run_claude
+
+logger = logging.getLogger(__name__)
+
+
+def _opt(arg: Any) -> Any:
+    """Underlying value of a runspec ``Arg`` (or the value as-is); '' -> None."""
+    value = getattr(arg, "value", arg)
+    if isinstance(value, str) and not value:
+        return None
+    return value
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload))
+
+
+def _run_turn(spec: rs.RunSpec, *, mode: str, session: str | None) -> None:
+    """Shared body for ask / continue / resume."""
+    result = run_claude(
+        str(spec.prompt.value),
+        mode=mode,
+        session=session,
+        model=_opt(spec.model),
+        cwd=_opt(spec.dir),
+        add_dir=_opt(spec.add_dir),
+        permission_mode=_opt(spec.permission_mode),
+        allowed_tools=_opt(spec.allowed_tools),
+        max_turns=_opt(spec.max_turns),
+        append_system_prompt=_opt(spec.append_system_prompt),
+        bare=bool(spec.bare.value),
+    )
+    if result.get("session_id"):
+        logger.info("session %s (%s turns)", result["session_id"], result.get("num_turns", "?"))
+    _emit(result)
+    if result.get("is_error"):
+        sys.exit(1)
+
+
+def main() -> None:
+    spec = rs.parse("claude-run")
+    command = spec.runspec_command
+
+    try:
+        if command == "ask":
+            _run_turn(spec, mode="ask", session=None)
+        elif command == "continue":
+            _run_turn(spec, mode="continue", session=None)
+        elif command == "resume":
+            _run_turn(spec, mode="resume", session=str(spec.session.value))
+        elif command == "sessions":
+            sessions = list_sessions(cwd=_opt(spec.dir), limit=int(spec.limit.value))
+            for s in sessions:
+                # Render the mtime as ISO for human/agent consumption.
+                s["modified"] = datetime.fromtimestamp(s["modified"], tz=timezone.utc).isoformat()
+            _emit({"sessions": sessions, "count": len(sessions)})
+        else:  # pragma: no cover - require-command makes this unreachable
+            _emit({"error": "no command — try: ask, continue, resume, sessions"})
+            sys.exit(2)
+    except ClaudeNotFoundError as exc:
+        _emit({"error": str(exc), "kind": "claude-not-found"})
+        sys.exit(127)
+    except ClaudeError as exc:
+        _emit({"error": str(exc)})
+        sys.exit(1)

runspec_claude-0.1.0/runspec_claude/runner.py

@@ -0,0 +1,280 @@
+"""runner.py — pure logic for driving the Claude Code CLI (`claude`) headlessly.
+
+No ``runspec`` dependency lives here: every function takes plain parameters and
+either returns plain data or raises a typed error. The thin CLI wrappers in
+:mod:`runspec_claude.cli` read args with ``runspec`` and call into here, so the
+same logic is importable by a private wrapper package that wants to bake in
+corporate defaults (a fixed model, allowlist, working directory, …).
+
+The headless contract is ``claude -p "<prompt>" --output-format json``; we parse
+the final JSON result object and normalise the fields we surface.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "ClaudeError",
+    "ClaudeNotFoundError",
+    "run_claude",
+    "list_sessions",
+    "encode_project_dir",
+]
+
+# Keys we lift out of the `--output-format json` result object. The CLI emits
+# more than this; we surface the stable, useful subset and keep the rest under
+# "raw" so nothing is silently lost.
+_RESULT_KEYS = ("result", "session_id", "is_error", "num_turns", "total_cost_usd", "duration_ms", "subtype")
+
+
+class ClaudeError(Exception):
+    """The ``claude`` CLI ran but failed, or its output could not be parsed."""
+
+
+class ClaudeNotFoundError(ClaudeError):
+    """The ``claude`` binary is not on PATH."""
+
+
+def _build_command(
+    *,
+    prompt: str | None,
+    mode: str,
+    session: str | None,
+    model: str | None,
+    add_dir: str | None,
+    permission_mode: str | None,
+    allowed_tools: str | None,
+    max_turns: int | None,
+    append_system_prompt: str | None,
+    bare: bool,
+    claude_bin: str,
+) -> list[str]:
+    """Assemble the argv for a headless ``claude`` invocation.
+
+    ``mode`` is one of ``"ask"`` (fresh run), ``"continue"`` (most recent
+    session in cwd) or ``"resume"`` (``session`` required).
+    """
+    cmd: list[str] = [claude_bin, "-p"]
+    if prompt is not None:
+        cmd.append(prompt)
+    cmd += ["--output-format", "json"]
+
+    if mode == "continue":
+        cmd.append("--continue")
+    elif mode == "resume":
+        if not session:
+            raise ClaudeError("resume requires a session id")
+        cmd += ["--resume", session]
+
+    if model:
+        cmd += ["--model", model]
+    if add_dir:
+        cmd += ["--add-dir", add_dir]
+    if permission_mode:
+        cmd += ["--permission-mode", permission_mode]
+    if allowed_tools:
+        cmd += ["--allowedTools", allowed_tools]
+    # max_turns of 0 (or None) means "leave it uncapped".
+    if max_turns:
+        cmd += ["--max-turns", str(max_turns)]
+    if append_system_prompt:
+        cmd += ["--append-system-prompt", append_system_prompt]
+    if bare:
+        cmd.append("--bare")
+    return cmd
+
+
+def _normalise_result(stdout: str) -> dict[str, Any]:
+    """Parse the `--output-format json` result object into our surfaced shape."""
+    text = stdout.strip()
+    if not text:
+        raise ClaudeError("claude produced no output")
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as exc:
+        # stream-json or an unexpected format: take the last non-empty JSON line.
+        payload = None
+        for line in reversed(text.splitlines()):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                payload = json.loads(line)
+                break
+            except json.JSONDecodeError:
+                continue
+        if payload is None:
+            raise ClaudeError(f"could not parse claude output as JSON: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise ClaudeError("unexpected claude output (not a JSON object)")
+
+    out: dict[str, Any] = {k: payload[k] for k in _RESULT_KEYS if k in payload}
+    out["raw"] = payload
+    return out
+
+
+def run_claude(
+    prompt: str | None,
+    *,
+    mode: str = "ask",
+    session: str | None = None,
+    model: str | None = None,
+    cwd: str | None = None,
+    add_dir: str | None = None,
+    permission_mode: str | None = "default",
+    allowed_tools: str | None = None,
+    max_turns: int | None = None,
+    append_system_prompt: str | None = None,
+    bare: bool = False,
+    claude_bin: str = "claude",
+    timeout: float | None = None,
+) -> dict[str, Any]:
+    """Run a headless ``claude`` turn and return the parsed result.
+
+    Returns a dict with (when present) ``result``, ``session_id``, ``is_error``,
+    ``num_turns``, ``total_cost_usd``, ``duration_ms`` and the full ``raw``
+    payload. ``is_error`` reflects the CLI's own flag — callers decide how to map
+    it to an exit code.
+
+    Raises :class:`ClaudeNotFoundError` if the binary is missing and
+    :class:`ClaudeError` on a non-zero exit with unparseable output, a timeout,
+    or output that is not JSON.
+    """
+    cmd = _build_command(
+        prompt=prompt,
+        mode=mode,
+        session=session,
+        model=model,
+        add_dir=add_dir,
+        permission_mode=permission_mode,
+        allowed_tools=allowed_tools,
+        max_turns=max_turns,
+        append_system_prompt=append_system_prompt,
+        bare=bare,
+        claude_bin=claude_bin,
+    )
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+            timeout=timeout,
+        )
+    except FileNotFoundError as exc:
+        raise ClaudeNotFoundError(f"the '{claude_bin}' CLI was not found on PATH — install Claude Code on this host") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise ClaudeError(f"claude timed out after {timeout}s") from exc
+
+    # The CLI usually still prints a JSON result (with is_error=true) on failure;
+    # prefer that over the raw exit code so the caller gets a structured answer.
+    if proc.stdout.strip():
+        return _normalise_result(proc.stdout)
+
+    if proc.returncode != 0:
+        detail = proc.stderr.strip() or f"claude exited with status {proc.returncode}"
+        raise ClaudeError(detail)
+    raise ClaudeError("claude produced no output")
+
+
+def encode_project_dir(path: str | os.PathLike[str]) -> str:
+    """Encode a working directory the way Claude Code names its transcript dir.
+
+    The project subdirectory under ``~/.claude/projects`` is the absolute path
+    with every non-alphanumeric character replaced by ``-``.
+    """
+    absolute = os.path.abspath(os.fspath(path))
+    return re.sub(r"[^a-zA-Z0-9]", "-", absolute)
+
+
+def _transcripts_root(config_dir: str | os.PathLike[str] | None) -> Path:
+    """Resolve the ``projects`` root, honouring ``CLAUDE_CONFIG_DIR``."""
+    if config_dir is not None:
+        base = Path(config_dir)
+    else:
+        env = os.environ.get("CLAUDE_CONFIG_DIR")
+        base = Path(env) if env else Path.home() / ".claude"
+    return base / "projects"
+
+
+def _sniff_title(transcript: Path) -> str | None:
+    """Best-effort human-readable title: the first user message text.
+
+    The JSONL line schema is undocumented, so this is defensive — it returns
+    ``None`` rather than raising on anything unexpected.
+    """
+    try:
+        with transcript.open(encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if not isinstance(obj, dict) or obj.get("type") != "user":
+                    continue
+                message = obj.get("message")
+                content = message.get("content") if isinstance(message, dict) else None
+                text = _content_text(content)
+                if text:
+                    return text[:120]
+    except OSError:
+        return None
+    return None
+
+
+def _content_text(content: Any) -> str | None:
+    """Pull plain text out of a message ``content`` (string or content blocks)."""
+    if isinstance(content, str):
+        return content.strip() or None
+    if isinstance(content, list):
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "text":
+                text = str(block.get("text", "")).strip()
+                if text:
+                    return text
+    return None
+
+
+def list_sessions(
+    *,
+    cwd: str | None = None,
+    config_dir: str | os.PathLike[str] | None = None,
+    limit: int = 20,
+) -> list[dict[str, Any]]:
+    """List recent Claude Code sessions for ``cwd`` (default: current directory).
+
+    Reads ``~/.claude/projects/<encoded-cwd>/<session-id>.jsonl`` (an
+    undocumented but stable layout) and returns the most-recently-modified
+    sessions first: ``{"session_id", "modified", "title", "path"}``. Returns an
+    empty list when the directory does not exist. ``title`` may be ``None``.
+    """
+    project_dir = _transcripts_root(config_dir) / encode_project_dir(cwd or os.getcwd())
+    if not project_dir.is_dir():
+        return []
+
+    transcripts = sorted(
+        project_dir.glob("*.jsonl"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    sessions: list[dict[str, Any]] = []
+    for transcript in transcripts[: max(limit, 0)]:
+        sessions.append(
+            {
+                "session_id": transcript.stem,
+                "modified": transcript.stat().st_mtime,
+                "title": _sniff_title(transcript),
+                "path": str(transcript),
+            }
+        )
+    return sessions

runspec_claude-0.1.0/runspec_claude/runspec.toml

@@ -0,0 +1,83 @@
+#:schema https://runspec.app/runspec.schema.json
+
+# runspec-claude — drive the Claude Code CLI (`claude`) headlessly from runspec.
+#
+# A single runnable, `claude-run`, with four verbs (subcommands) that mirror the
+# way you talk to Claude in a chat app:
+#
+#   claude-run ask      "<prompt>"            start a fresh headless turn / session
+#   claude-run continue "<prompt>"            continue the most recent session here
+#   claude-run resume   --session <id> "..."  continue a specific session by id
+#   claude-run sessions                       list recent sessions for this directory
+#
+# Each verb shells out to `claude -p ... --output-format json` and returns the
+# structured result (text + session id + cost + turns). Because `runspec serve`
+# exposes each leaf subcommand as its own MCP tool, the runspec-console agent
+# (itself Claude) can call these to delegate a bounded sub-task to a headless
+# Claude Code — "Claude driving Claude" — with a human confirm gate by default.
+
+[config]
+# Spawning an agent that can read/run/edit is a confirm-by-default action.
+autonomy-default = "confirm"
+
+[config.logging]
+# One log file per invocation — multi-writer safe for shared venvs.
+store = "per-run"
+
+[claude-run]
+description     = "Drive the Claude Code CLI headlessly (ask / continue / resume / sessions)"
+autonomy        = "confirm"
+output          = "json"
+require-command = true
+
+examples = [
+  {cmd = "claude-run ask 'summarise the failures in build.log'",            description = "One-shot headless turn (read-only by default)"},
+  {cmd = "claude-run --permission-mode acceptEdits ask 'fix the lint errors'", description = "Let the delegated run edit files + run safe commands"},
+  {cmd = "claude-run continue 'now write a test for that fix'",             description = "Continue the most recent session in this directory"},
+  {cmd = "claude-run resume --session 8f2c... 'and update the changelog'",  description = "Continue a specific prior session by id"},
+  {cmd = "claude-run sessions",                                             description = "List recent sessions you can resume"},
+]
+
+# ---- Global arguments (inherited by every subcommand) --------------------
+[claude-run.args]
+model               = {type = "str",    short = "-m", required = false, description = "Model for the headless run: an alias (sonnet, opus, haiku, fable, opusplan) or a full id like claude-opus-4-8. Default: the CLI's configured model."}
+dir                 = {type = "path",   short = "-C", required = false, description = "Working directory to run claude in (scopes file access, --continue, and the sessions list). Default: current directory."}
+add-dir             = {type = "path",                 required = false, description = "Extra directory to grant the run access to (passed to --add-dir)."}
+permission-mode     = {type = "choice", short = "-P", default = "default", options = ["default", "plan", "acceptEdits", "auto", "dontAsk", "bypassPermissions"], description = "How the headless run handles tool permissions. Safe 'default' blocks on edits/commands; opt up to acceptEdits/auto for autonomous work. 'bypassPermissions' skips all checks — use with care."}
+allowed-tools       = {type = "str",                  required = false, description = "Comma-separated tool allowlist passed to --allowedTools, e.g. 'Read,Bash(git diff *)'."}
+max-turns           = {type = "int",    short = "-t", default = 12, description = "Cap on agent turns before the run stops (bounds cost/runaway). 0 leaves it uncapped."}
+append-system-prompt = {type = "str",                 required = false, description = "Extra system-prompt text appended for this run (passed to --append-system-prompt)."}
+bare                = {type = "flag",                 default = false, description = "Reproducible run: skip auto-discovery of CLAUDE.md, hooks, skills, plugins, and MCP servers (--bare)."}
+
+# ---- ask: start a fresh headless turn ------------------------------------
+[claude-run.commands.ask]
+description = "Send a prompt to a fresh headless Claude Code run"
+autonomy    = "confirm"
+
+[claude-run.commands.ask.args]
+prompt = {type = "str", required = true, description = "The instruction/question for Claude Code."}
+
+# ---- continue: continue the most recent session in this directory --------
+[claude-run.commands.continue]
+description = "Continue the most recent session in this directory with a follow-up message"
+autonomy    = "confirm"
+
+[claude-run.commands.continue.args]
+prompt = {type = "str", required = true, description = "The follow-up message to send to the most recent session."}
+
+# ---- resume: continue a specific session by id ---------------------------
+[claude-run.commands.resume]
+description = "Resume a specific prior session by id and send a follow-up message"
+autonomy    = "confirm"
+
+[claude-run.commands.resume.args]
+session = {type = "str", short = "-s", required = true, description = "Session id to resume (see `claude-run sessions`)."}
+prompt  = {type = "str",              required = true, description = "The follow-up message to send to the resumed session."}
+
+# ---- sessions: list recent sessions for this directory -------------------
+[claude-run.commands.sessions]
+description = "List recent Claude Code sessions for this directory (ids, last-active time, best-effort title). Read-only; reads local transcript files."
+autonomy    = "autonomous"
+
+[claude-run.commands.sessions.args]
+limit = {type = "int", short = "-n", default = 20, description = "Maximum number of recent sessions to list."}

runspec_claude-0.1.0/tests/test_runner.py

@@ -0,0 +1,250 @@
+"""Tests for the pure runner logic (no `claude` binary or runspec parsing)."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+
+import pytest
+
+from runspec_claude.runner import (
+    ClaudeError,
+    ClaudeNotFoundError,
+    _build_command,
+    _normalise_result,
+    encode_project_dir,
+    list_sessions,
+    run_claude,
+)
+
+
+def test_build_command_ask_minimal():
+    cmd = _build_command(
+        prompt="hello",
+        mode="ask",
+        session=None,
+        model=None,
+        add_dir=None,
+        permission_mode=None,
+        allowed_tools=None,
+        max_turns=None,
+        append_system_prompt=None,
+        bare=False,
+        claude_bin="claude",
+    )
+    assert cmd == ["claude", "-p", "hello", "--output-format", "json"]
+
+
+def test_build_command_all_flags():
+    cmd = _build_command(
+        prompt="do it",
+        mode="ask",
+        session=None,
+        model="opus",
+        add_dir="/extra",
+        permission_mode="acceptEdits",
+        allowed_tools="Read,Bash",
+        max_turns=5,
+        append_system_prompt="be terse",
+        bare=True,
+        claude_bin="claude",
+    )
+    assert "--model" in cmd and cmd[cmd.index("--model") + 1] == "opus"
+    assert "--add-dir" in cmd and cmd[cmd.index("--add-dir") + 1] == "/extra"
+    assert "--permission-mode" in cmd and cmd[cmd.index("--permission-mode") + 1] == "acceptEdits"
+    assert "--allowedTools" in cmd and cmd[cmd.index("--allowedTools") + 1] == "Read,Bash"
+    assert "--max-turns" in cmd and cmd[cmd.index("--max-turns") + 1] == "5"
+    assert "--append-system-prompt" in cmd
+    assert "--bare" in cmd
+
+
+def test_build_command_continue_and_resume():
+    cont = _build_command(
+        prompt="more",
+        mode="continue",
+        session=None,
+        model=None,
+        add_dir=None,
+        permission_mode=None,
+        allowed_tools=None,
+        max_turns=None,
+        append_system_prompt=None,
+        bare=False,
+        claude_bin="claude",
+    )
+    assert "--continue" in cont
+
+    res = _build_command(
+        prompt="more",
+        mode="resume",
+        session="abc123",
+        model=None,
+        add_dir=None,
+        permission_mode=None,
+        allowed_tools=None,
+        max_turns=None,
+        append_system_prompt=None,
+        bare=False,
+        claude_bin="claude",
+    )
+    assert res[res.index("--resume") + 1] == "abc123"
+
+
+def test_build_command_resume_requires_session():
+    with pytest.raises(ClaudeError, match="session id"):
+        _build_command(
+            prompt="x",
+            mode="resume",
+            session=None,
+            model=None,
+            add_dir=None,
+            permission_mode=None,
+            allowed_tools=None,
+            max_turns=None,
+            append_system_prompt=None,
+            bare=False,
+            claude_bin="claude",
+        )
+
+
+def test_max_turns_zero_is_uncapped():
+    cmd = _build_command(
+        prompt="x",
+        mode="ask",
+        session=None,
+        model=None,
+        add_dir=None,
+        permission_mode=None,
+        allowed_tools=None,
+        max_turns=0,
+        append_system_prompt=None,
+        bare=False,
+        claude_bin="claude",
+    )
+    assert "--max-turns" not in cmd
+
+
+def test_normalise_result_picks_known_keys():
+    raw = {
+        "type": "result",
+        "subtype": "success",
+        "is_error": False,
+        "num_turns": 3,
+        "result": "done",
+        "session_id": "s1",
+        "total_cost_usd": 0.01,
+        "extra": "ignored-at-top-level",
+    }
+    out = _normalise_result(json.dumps(raw))
+    assert out["result"] == "done"
+    assert out["session_id"] == "s1"
+    assert out["is_error"] is False
+    assert out["raw"]["extra"] == "ignored-at-top-level"
+
+
+def test_normalise_result_falls_back_to_last_json_line():
+    stream = '{"type":"system"}\nnot json\n{"result":"final","session_id":"s2"}\n'
+    out = _normalise_result(stream)
+    assert out["result"] == "final"
+    assert out["session_id"] == "s2"
+
+
+def test_normalise_result_empty_raises():
+    with pytest.raises(ClaudeError, match="no output"):
+        _normalise_result("   ")
+
+
+def test_normalise_result_unparseable_raises():
+    with pytest.raises(ClaudeError, match="could not parse"):
+        _normalise_result("definitely not json at all")
+
+
+def test_encode_project_dir():
+    assert encode_project_dir("/Users/me/proj") == "-Users-me-proj"
+    assert encode_project_dir("/a.b/c_d") == "-a-b-c-d"
+
+
+def test_run_claude_missing_binary(monkeypatch):
+    def boom(*a, **k):
+        raise FileNotFoundError("claude")
+
+    monkeypatch.setattr(subprocess, "run", boom)
+    with pytest.raises(ClaudeNotFoundError):
+        run_claude("hi", claude_bin="claude")
+
+
+def test_run_claude_parses_stdout(monkeypatch):
+    class FakeProc:
+        returncode = 0
+        stdout = '{"result":"ok","session_id":"s9","is_error":false}'
+        stderr = ""
+
+    monkeypatch.setattr(subprocess, "run", lambda *a, **k: FakeProc())
+    out = run_claude("hi")
+    assert out["result"] == "ok"
+    assert out["session_id"] == "s9"
+
+
+def test_run_claude_timeout(monkeypatch):
+    def boom(*a, **k):
+        raise subprocess.TimeoutExpired(cmd="claude", timeout=1)
+
+    monkeypatch.setattr(subprocess, "run", boom)
+    with pytest.raises(ClaudeError, match="timed out"):
+        run_claude("hi", timeout=1)
+
+
+def test_run_claude_nonzero_no_output(monkeypatch):
+    class FakeProc:
+        returncode = 1
+        stdout = ""
+        stderr = "auth failed"
+
+    monkeypatch.setattr(subprocess, "run", lambda *a, **k: FakeProc())
+    with pytest.raises(ClaudeError, match="auth failed"):
+        run_claude("hi")
+
+
+def test_list_sessions_empty_when_missing(tmp_path):
+    sessions = list_sessions(cwd=str(tmp_path / "nope"), config_dir=tmp_path / "cfg")
+    assert sessions == []
+
+
+def test_list_sessions_reads_and_sorts(tmp_path):
+    cwd = "/work/project"
+    config_dir = tmp_path / "claude"
+    project_dir = config_dir / "projects" / encode_project_dir(cwd)
+    project_dir.mkdir(parents=True)
+
+    old = project_dir / "old-session.jsonl"
+    old.write_text(
+        json.dumps({"type": "user", "message": {"content": "first question"}}) + "\n",
+        encoding="utf-8",
+    )
+    new = project_dir / "new-session.jsonl"
+    new.write_text(
+        json.dumps({"type": "user", "message": {"content": [{"type": "text", "text": "newer question"}]}}) + "\n",
+        encoding="utf-8",
+    )
+    # Make `new` more recent.
+    import os
+
+    os.utime(old, (1000, 1000))
+    os.utime(new, (2000, 2000))
+
+    sessions = list_sessions(cwd=cwd, config_dir=config_dir)
+    assert [s["session_id"] for s in sessions] == ["new-session", "old-session"]
+    assert sessions[0]["title"] == "newer question"
+    assert sessions[1]["title"] == "first question"
+
+
+def test_list_sessions_limit(tmp_path):
+    cwd = "/work/x"
+    config_dir = tmp_path / "claude"
+    project_dir = config_dir / "projects" / encode_project_dir(cwd)
+    project_dir.mkdir(parents=True)
+    for i in range(5):
+        (project_dir / f"s{i}.jsonl").write_text("{}\n", encoding="utf-8")
+
+    sessions = list_sessions(cwd=cwd, config_dir=config_dir, limit=2)
+    assert len(sessions) == 2

runspec_claude-0.1.0/tests/test_spec.py

@@ -0,0 +1,27 @@
+"""The bundled runspec.toml must load and expose the four subcommands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import runspec as rs
+
+_SPEC = Path(__file__).resolve().parent.parent / "runspec_claude" / "runspec.toml"
+
+
+def test_spec_loads():
+    spec = rs.load_spec("claude-run", config_path=_SPEC)
+    assert spec.runspec_runnable == "claude-run"
+
+
+def test_subcommands_present():
+    spec = rs.load_spec("claude-run", config_path=_SPEC)
+    commands = set(spec.runspec_spec.get("commands", {}))
+    assert commands == {"ask", "continue", "resume", "sessions"}
+
+
+def test_global_args_inherited():
+    spec = rs.load_spec("claude-run", config_path=_SPEC)
+    args = spec.runspec_spec.get("args", {})
+    assert "permission-mode" in args
+    assert args["permission-mode"]["default"] == "default"