shikiru-cli 0.2.0__py3-none-any.whl

shikiru/plugins/agents/claude/agent.py

@@ -0,0 +1,251 @@
+"""Claude Code headless turn plugin."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import TYPE_CHECKING, cast
+
+from pydantic import ValidationError
+
+from shikiru.agents.contracts import (
+    BILLING_SOURCE_OPERATOR_CONFIG,
+    DOCTOR_TIMEOUT_SECONDS,
+    UNKNOWN_BILLING_DECLARATION,
+    BillingDeclaration,
+    CheckResult,
+    ModelCatalog,
+)
+from shikiru.agents.sdk.reset_time import ResetTimeParser
+from shikiru.agents.sdk.turn import StreamingTurn
+from shikiru.errors import CommandFailed, ShikiruError
+from shikiru.plugins.agents.claude.headless import ClaudeHeadless
+from shikiru.plugins.agents.claude.model_catalog import parse_model_catalog
+from shikiru.plugins.agents.claude.options import (
+    ADD_DIR_FLAG,
+    CLAUDE_COMMAND,
+    CLAUDE_SETTINGS,
+    EFFORT_FLAG,
+    EMPTY_MCP_CONFIG,
+    EMPTY_TOOLS,
+    INPUT_FORMAT_FLAG,
+    MCP_CONFIG_FLAG,
+    MODEL_CATALOG_REQUEST_ID,
+    MODEL_FLAG,
+    NO_SESSION_PERSISTENCE_FLAG,
+    OUTPUT_FORMAT_FLAG,
+    PRINT_FLAG,
+    RESUME_FLAG,
+    SAFE_MODE_FLAG,
+    STREAM_JSON_FORMAT,
+    STRICT_MCP_CONFIG_FLAG,
+    TOOLS_FLAG,
+    VERBOSE_FLAG,
+    ClaudeOptions,
+)
+from shikiru.plugins.agents.claude.turn import ClaudeTurnSequence
+from shikiru.plugins.agents.shared_settings import options_error
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from shikiru.agents.contracts import AgentContext, HeadlessAgent, Rung, Turn, TurnSpec
+    from shikiru.agents.settings import AgentSetting
+    from shikiru.clock import Clock
+    from shikiru.process import SubprocessRunner
+
+CLAUDE_VERSION_ARGV = (CLAUDE_COMMAND, "--version")
+AUTH_STATUS_ARGV = (CLAUDE_COMMAND, "auth", "status", "--json")
+_AUTH_STATUS_LOGGED_IN_FIELD = "loggedIn"
+_INVALID_AUTH_STATUS_MESSAGE = "Claude auth status did not return valid JSON"
+_MODEL_CATALOG_TIMEOUT_SECONDS = 20.0
+_CONTROL_REQUEST_TYPE = "control_request"
+_INITIALIZE_SUBTYPE = "initialize"
+_MODEL_CATALOG_REQUEST = json.dumps(
+    {
+        "type": _CONTROL_REQUEST_TYPE,
+        "request_id": MODEL_CATALOG_REQUEST_ID,
+        "request": {
+            "subtype": _INITIALIZE_SUBTYPE,
+            "hooks": {},
+        },
+    },
+    separators=(",", ":"),
+)
+
+
+class ClaudeAgent:
+    """Build Claude Code turn processes and health checks."""
+
+    name = "claude"
+
+    def __init__(self, runner: SubprocessRunner, clock: Clock, options: ClaudeOptions) -> None:
+        self._runner = runner
+        self._clock = clock
+        self._options = options
+        self._reset_time = ResetTimeParser(clock)
+        self._billing_declaration = (
+            BillingDeclaration(options.billing_mode, BILLING_SOURCE_OPERATOR_CONFIG)
+            if options.billing_mode is not None
+            else UNKNOWN_BILLING_DECLARATION
+        )
+
+    @property
+    def billing_declaration(self) -> BillingDeclaration:
+        """Return the explicit plugin option or the unknown declaration."""
+        return self._billing_declaration
+
+    async def model_catalog(self) -> ModelCatalog:
+        """Read model and per-model effort choices from Claude Code's initialize response."""
+        argv = (
+            CLAUDE_COMMAND,
+            PRINT_FLAG,
+            INPUT_FORMAT_FLAG,
+            STREAM_JSON_FORMAT,
+            OUTPUT_FORMAT_FLAG,
+            STREAM_JSON_FORMAT,
+            VERBOSE_FLAG,
+            NO_SESSION_PERSISTENCE_FLAG,
+            SAFE_MODE_FLAG,
+            STRICT_MCP_CONFIG_FLAG,
+            MCP_CONFIG_FLAG,
+            EMPTY_MCP_CONFIG,
+            TOOLS_FLAG,
+            EMPTY_TOOLS,
+        )
+        try:
+            with TemporaryDirectory() as isolated_directory:
+                result = await self._runner.run(
+                    argv,
+                    timeout=_MODEL_CATALOG_TIMEOUT_SECONDS,
+                    cwd=Path(isolated_directory),
+                    env=self._subprocess_environment(),
+                    input_text=f"{_MODEL_CATALOG_REQUEST}\n",
+                    check=False,
+                )
+        except (FileNotFoundError, OSError, ShikiruError, TimeoutError) as error:
+            detail = str(error) or type(error).__name__
+            return ModelCatalog(error=f"Claude Code model discovery command failed: {detail}")
+        if result.returncode != 0:
+            detail = result.stderr.strip() or "no diagnostic output"
+            return ModelCatalog(
+                error=f"Claude Code model discovery exited with code {result.returncode}: {detail}"
+            )
+        try:
+            return parse_model_catalog(result.stdout, MODEL_CATALOG_REQUEST_ID)
+        except TypeError as error:
+            return ModelCatalog(error=f"could not parse Claude Code model catalog: {error}")
+
+    async def start_turn(self, spec: TurnSpec) -> Turn:
+        """Start one process-per-turn Claude Code exchange."""
+        return await StreamingTurn.start(spec, self._runner, self.process_sequence(spec))
+
+    def process_sequence(self, spec: TurnSpec) -> ClaudeTurnSequence:
+        """Build the compact, prompt and retry process sequence for `spec`."""
+        return ClaudeTurnSequence(
+            spec,
+            clock=self._clock,
+            reset_time=self._reset_time,
+            compact_at_pct=self._options.compact_at_pct,
+            args=self._options.args,
+            environment=self._turn_environment,
+        )
+
+    def interactive_command(self, session_id: str, run_dir: Path, rung: Rung) -> Sequence[str]:
+        """Return Claude's interactive resume command for a headless session and rung."""
+        argv = [CLAUDE_COMMAND, RESUME_FLAG, session_id, MODEL_FLAG, rung.model]
+        if rung.effort is not None:
+            argv.extend((EFFORT_FLAG, rung.effort))
+        argv.extend((ADD_DIR_FLAG, str(run_dir), *self._options.args))
+        return tuple(argv)
+
+    async def doctor(self, models: Sequence[str]) -> list[CheckResult]:
+        """Check Claude's binary, version and authentication."""
+        del models
+        binary = await self._check_binary()
+        if not binary.ok:
+            unavailable = "binary unavailable"
+            return [
+                binary,
+                CheckResult("version", False, unavailable),
+                CheckResult("login", False, unavailable),
+            ]
+        return [binary, await self._check_version(), await self._check_login()]
+
+    def settings(self) -> tuple[AgentSetting, ...]:
+        """Return the options worth writing to the project config."""
+        return CLAUDE_SETTINGS
+
+    def headless(self) -> HeadlessAgent | None:
+        """Return Claude's schema-constrained headless client."""
+        return ClaudeHeadless(self._runner, self._subprocess_environment())
+
+    def _subprocess_environment(self) -> dict[str, str]:
+        return dict(os.environ)
+
+    def _turn_environment(self, spec: TurnSpec) -> dict[str, str]:
+        environment = dict(os.environ)
+        environment.update(spec.env)
+        return environment
+
+    async def _check_binary(self) -> CheckResult:
+        try:
+            result = await self._runner.run(
+                CLAUDE_VERSION_ARGV,
+                timeout=DOCTOR_TIMEOUT_SECONDS,
+                env=self._subprocess_environment(),
+                check=False,
+            )
+        except (FileNotFoundError, CommandFailed, ShikiruError) as error:
+            return CheckResult("binary", False, str(error))
+        if result.returncode != 0:
+            return CheckResult("binary", False, result.stderr.strip())
+        return CheckResult("binary", True, CLAUDE_COMMAND)
+
+    async def _check_version(self) -> CheckResult:
+        try:
+            result = await self._runner.run(
+                CLAUDE_VERSION_ARGV,
+                timeout=DOCTOR_TIMEOUT_SECONDS,
+                env=self._subprocess_environment(),
+                check=False,
+            )
+        except (FileNotFoundError, ShikiruError) as error:
+            return CheckResult("version", False, str(error))
+        detail = result.stdout.strip() or result.stderr.strip()
+        return CheckResult("version", result.returncode == 0, detail)
+
+    async def _check_login(self) -> CheckResult:
+        try:
+            result = await self._runner.run(
+                AUTH_STATUS_ARGV,
+                timeout=DOCTOR_TIMEOUT_SECONDS,
+                env=self._subprocess_environment(),
+                check=False,
+            )
+        except (FileNotFoundError, ShikiruError) as error:
+            return CheckResult("login", False, str(error))
+        try:
+            payload = json.loads(result.stdout)
+        except json.JSONDecodeError:
+            return CheckResult("login", False, _INVALID_AUTH_STATUS_MESSAGE)
+        if not isinstance(payload, Mapping):
+            return CheckResult("login", False, _INVALID_AUTH_STATUS_MESSAGE)
+        typed_payload = cast("Mapping[str, object]", payload)
+        authenticated = (
+            result.returncode == 0 and typed_payload.get(_AUTH_STATUS_LOGGED_IN_FIELD) is True
+        )
+        detail = "authenticated" if authenticated else "not authenticated"
+        return CheckResult("login", authenticated, detail)
+
+
+def create(context: AgentContext) -> ClaudeAgent:
+    """Build the Claude Code plugin from validated `AgentContext.options`."""
+    try:
+        options = ClaudeOptions.model_validate(context.options)
+    except ValidationError as error:
+        raise options_error(CLAUDE_COMMAND, error) from error
+    return ClaudeAgent(context.runner, context.clock, options)

shikiru/plugins/agents/claude/context.py

@@ -0,0 +1,116 @@
+"""Claude's context window and next-request token estimate used for compaction decisions."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+    from pathlib import Path
+
+CONTEXT_WINDOW_TOKENS = 200_000
+EXTENDED_CONTEXT_WINDOW_TOKENS = 1_000_000
+EXTENDED_CONTEXT_MODEL_SUFFIX = "[1m]"
+CHARS_PER_TOKEN = 3
+_PERCENT = 100
+_TYPE_FIELD = "type"
+_ASSISTANT_TYPE = "assistant"
+_USER_TYPE = "user"
+_TOOL_RESULT_TYPE = "tool_result"
+_MESSAGE_FIELD = "message"
+_ID_FIELD = "id"
+_USAGE_FIELD = "usage"
+_CONTENT_FIELD = "content"
+_CONTEXT_USAGE_FIELDS = (
+    "input_tokens",
+    "cache_read_input_tokens",
+    "cache_creation_input_tokens",
+    "output_tokens",
+)
+
+
+def compact_limit_tokens(model: str, compact_at_pct: float) -> int:
+    """Return the tokens at which a request on `model` must be preceded by compaction."""
+    window = (
+        EXTENDED_CONTEXT_WINDOW_TOKENS
+        if model.endswith(EXTENDED_CONTEXT_MODEL_SUFFIX)
+        else CONTEXT_WINDOW_TOKENS
+    )
+    return int(window * compact_at_pct / _PERCENT)
+
+
+def pending_tokens(value: object) -> int:
+    """Estimate the tokens a tool result adds to the next request."""
+    return len(json.dumps(value)) // CHARS_PER_TOKEN
+
+
+def read_transcript(path: Path) -> list[Mapping[str, Any]]:
+    """Return the JSON object entries of a Claude session transcript."""
+    entries: list[Mapping[str, Any]] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        raw = json.loads(line)
+        if isinstance(raw, Mapping):
+            entries.append(cast("Mapping[str, Any]", raw))
+    return entries
+
+
+def last_assistant_context(entries: Iterable[Mapping[str, Any]]) -> tuple[str | None, int]:
+    """Return the id of the last assistant message and the context its request used."""
+    message_id: str | None = None
+    tokens = 0
+    for entry in entries:
+        message = _assistant_message(entry)
+        if message is not None:
+            raw_id = message.get(_ID_FIELD)
+            message_id = raw_id if isinstance(raw_id, str) else None
+            tokens = _usage_tokens(message.get(_USAGE_FIELD))
+    return message_id, tokens
+
+
+def transcript_context_tokens(entries: Iterable[Mapping[str, Any]]) -> int:
+    """Estimate the next request: the last assistant context plus the tool results since."""
+    tokens = 0
+    pending = 0
+    for entry in entries:
+        message = _assistant_message(entry)
+        if message is not None:
+            tokens = _usage_tokens(message.get(_USAGE_FIELD))
+            pending = 0
+        else:
+            pending += sum(pending_tokens(result) for result in _tool_results(entry))
+    return tokens + pending
+
+
+def _assistant_message(entry: Mapping[str, Any]) -> Mapping[str, Any] | None:
+    if entry.get(_TYPE_FIELD) != _ASSISTANT_TYPE:
+        return None
+    return _mapping(entry.get(_MESSAGE_FIELD))
+
+
+def _tool_results(entry: Mapping[str, Any]) -> list[object]:
+    message = _mapping(entry.get(_MESSAGE_FIELD)) if entry.get(_TYPE_FIELD) == _USER_TYPE else None
+    blocks = message.get(_CONTENT_FIELD) if message is not None else None
+    if not isinstance(blocks, list):
+        return []
+    return [
+        block.get(_CONTENT_FIELD)
+        for item in cast("list[object]", blocks)
+        if (block := _mapping(item)) is not None and block.get(_TYPE_FIELD) == _TOOL_RESULT_TYPE
+    ]
+
+
+def _usage_tokens(value: object) -> int:
+    usage = _mapping(value)
+    if usage is None:
+        return 0
+    return sum(
+        int(amount)
+        for field in _CONTEXT_USAGE_FIELDS
+        if isinstance(amount := usage.get(field), int | float)
+    )
+
+
+def _mapping(value: object) -> Mapping[str, Any] | None:
+    return cast("Mapping[str, Any]", value) if isinstance(value, Mapping) else None

shikiru/plugins/agents/claude/headless.py

@@ -0,0 +1,92 @@
+"""Claude Code schema-constrained one-shot calls."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, cast
+
+from shikiru.errors import HeadlessOutputError
+from shikiru.plugins.agents.claude.options import (
+    CLAUDE_COMMAND,
+    EFFORT_FLAG,
+    EMPTY_TOOLS,
+    MODEL_FLAG,
+    NO_SESSION_PERSISTENCE_FLAG,
+    OUTPUT_FORMAT_FLAG,
+    PRINT_FLAG,
+    SAFE_MODE_FLAG,
+    TOOLS_FLAG,
+)
+
+if TYPE_CHECKING:
+    from datetime import timedelta
+    from pathlib import Path
+
+    from shikiru.process import SubprocessRunner
+
+_OUTPUT_FORMAT_JSON = "json"
+_JSON_SCHEMA_FLAG = "--json-schema"
+_STRUCTURED_OUTPUT_FIELD = "structured_output"
+_INVALID_JSON_MESSAGE = "Claude headless output was not valid JSON"
+_INVALID_OBJECT_MESSAGE = "Claude headless output was not an object"
+_MISSING_STRUCTURED_OUTPUT_MESSAGE = "Claude headless output had no structured_output"
+
+
+class ClaudeHeadless:
+    """Runs Claude Code's JSON structured-output mode."""
+
+    def __init__(self, runner: SubprocessRunner, environment: Mapping[str, str]) -> None:
+        """Use `runner` and the operator's inherited Claude environment."""
+        self._runner = runner
+        self._environment = dict(environment)
+
+    async def ask(
+        self,
+        prompt: str,
+        schema: Mapping[str, Any],
+        model: str,
+        effort: str | None,
+        cwd: Path,
+        timeout: timedelta,
+    ) -> Mapping[str, Any]:
+        """Return Claude's schema-constrained `structured_output` value."""
+        argv = [
+            CLAUDE_COMMAND,
+            PRINT_FLAG,
+            OUTPUT_FORMAT_FLAG,
+            _OUTPUT_FORMAT_JSON,
+            _JSON_SCHEMA_FLAG,
+            json.dumps(schema, separators=(",", ":")),
+            MODEL_FLAG,
+            model,
+        ]
+        if effort is not None:
+            argv.extend([EFFORT_FLAG, effort])
+        argv.extend(
+            [
+                SAFE_MODE_FLAG,
+                TOOLS_FLAG,
+                EMPTY_TOOLS,
+                NO_SESSION_PERSISTENCE_FLAG,
+            ]
+        )
+        result = await self._runner.run(
+            argv,
+            timeout=timeout.total_seconds(),
+            cwd=cwd,
+            env=self._environment,
+            input_text=prompt,
+            check=True,
+        )
+        try:
+            payload = json.loads(result.stdout)
+        except json.JSONDecodeError as error:
+            raise HeadlessOutputError(_INVALID_JSON_MESSAGE) from error
+        if not isinstance(payload, Mapping):
+            raise HeadlessOutputError(_INVALID_OBJECT_MESSAGE)
+        typed_payload = cast("Mapping[str, Any]", payload)
+        structured = typed_payload.get(_STRUCTURED_OUTPUT_FIELD)
+        if not isinstance(structured, Mapping):
+            raise HeadlessOutputError(_MISSING_STRUCTURED_OUTPUT_MESSAGE)
+        return cast("Mapping[str, Any]", structured)

shikiru/plugins/agents/claude/hook.py

@@ -0,0 +1,57 @@
+"""Claude `PostToolUse` hook: stop the turn before a request would cross the limit.
+
+Run as `<python> -P -m shikiru.plugins.agents.claude.hook <state> <marker> <limit_tokens>`.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from shikiru.plugins.agents.claude.context import (
+    last_assistant_context,
+    pending_tokens,
+    read_transcript,
+)
+
+TRANSCRIPT_PATH_FIELD = "transcript_path"
+TOOL_RESPONSE_FIELD = "tool_response"
+STOP_REASON = "Shikiru: context threshold reached; compacting before the next request"
+_CONTINUE_FIELD = "continue"
+_STOP_REASON_FIELD = "stopReason"
+_STATE_ID_FIELD = "id"
+_STATE_TOKENS_FIELD = "tokens"
+
+
+def main() -> None:
+    """Record this tool result and stop the turn once the next request reaches the limit."""
+    _, state_argument, marker_argument, limit_argument = sys.argv
+    state_path, marker_path, limit = (
+        Path(state_argument),
+        Path(marker_argument),
+        int(limit_argument),
+    )
+    event = json.load(sys.stdin)
+    message_id, context = last_assistant_context(
+        read_transcript(Path(event[TRANSCRIPT_PATH_FIELD]))
+    )
+    pending = _record_pending(
+        state_path, message_id, pending_tokens(event.get(TOOL_RESPONSE_FIELD))
+    )
+    if context + pending >= limit:
+        marker_path.touch()
+        json.dump({_CONTINUE_FIELD: False, _STOP_REASON_FIELD: STOP_REASON}, sys.stdout)
+
+
+def _record_pending(state_path: Path, message_id: str | None, tokens: int) -> int:
+    with state_path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps({_STATE_ID_FIELD: message_id, _STATE_TOKENS_FIELD: tokens}) + "\n")
+    records = [json.loads(line) for line in state_path.read_text(encoding="utf-8").splitlines()]
+    return sum(
+        record[_STATE_TOKENS_FIELD] for record in records if record[_STATE_ID_FIELD] == message_id
+    )
+
+
+if __name__ == "__main__":
+    main()

shikiru/plugins/agents/claude/model_catalog.py

@@ -0,0 +1,105 @@
+"""Claude Code initialize response model catalog parsing."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any, cast
+
+from shikiru.agents.contracts import ModelCatalog, ModelChoice
+
+_CONTROL_RESPONSE_TYPE = "control_response"
+_SUCCESS_SUBTYPE = "success"
+_INVALID_RESPONSE = "Claude Code initialize response has an invalid model catalog"
+_INVALID_JSON = "Claude Code initialize output is not valid stream JSON"
+
+
+def parse_model_catalog(output: str, request_id: str) -> ModelCatalog:
+    """Parse only model choices from the matching Claude Code initialize response."""
+    response = _matching_initialize_response(output, request_id)
+    raw_models = response.get("models")
+    if not isinstance(raw_models, list) or not raw_models:
+        raise TypeError(_INVALID_RESPONSE)
+    return ModelCatalog(models=_catalog_choices(cast("list[object]", raw_models)))
+
+
+def _matching_initialize_response(output: str, request_id: str) -> Mapping[str, Any]:
+    response: Mapping[str, Any] | None = None
+    for line in output.splitlines():
+        if not line.strip():
+            continue
+        try:
+            raw_message = json.loads(line)
+        except json.JSONDecodeError as error:
+            raise TypeError(_INVALID_JSON) from error
+        if not isinstance(raw_message, Mapping):
+            raise TypeError(_INVALID_RESPONSE)
+        message = cast("Mapping[str, Any]", raw_message)
+        control_response = message.get("response")
+        if message.get("type") != _CONTROL_RESPONSE_TYPE or not isinstance(
+            control_response, Mapping
+        ):
+            continue
+        typed_response = cast("Mapping[str, Any]", control_response)
+        if typed_response.get("request_id") != request_id:
+            continue
+        if typed_response.get("subtype") != _SUCCESS_SUBTYPE:
+            raise TypeError(_INVALID_RESPONSE)
+        initialize_response = typed_response.get("response")
+        if not isinstance(initialize_response, Mapping):
+            raise TypeError(_INVALID_RESPONSE)
+        response = cast("Mapping[str, Any]", initialize_response)
+        break
+    if response is None:
+        raise TypeError(_INVALID_RESPONSE)
+    return response
+
+
+def _catalog_choices(raw_models: list[object]) -> tuple[ModelChoice, ...]:
+    choices: dict[str, ModelChoice] = {}
+    for raw_model in raw_models:
+        for choice in _model_choices(raw_model):
+            existing = choices.get(choice.model)
+            if existing is not None and existing.efforts != choice.efforts:
+                raise TypeError(_INVALID_RESPONSE)
+            choices[choice.model] = choice
+    return tuple(choices.values())
+
+
+def _model_choices(raw_model: object) -> tuple[ModelChoice, ...]:
+    if not isinstance(raw_model, Mapping):
+        raise TypeError(_INVALID_RESPONSE)
+    model = cast("Mapping[str, Any]", raw_model)
+    value = model.get("value")
+    if not isinstance(value, str) or not value:
+        raise TypeError(_INVALID_RESPONSE)
+    efforts = _efforts(model)
+    identifiers = [value]
+    resolved = model.get("resolvedModel")
+    if resolved is not None:
+        if not isinstance(resolved, str) or not resolved:
+            raise TypeError(_INVALID_RESPONSE)
+        identifiers.append(resolved)
+    unique_identifiers = tuple(dict.fromkeys(identifiers))
+    return tuple(
+        ModelChoice(model=identifier, efforts=efforts) for identifier in unique_identifiers
+    )
+
+
+def _efforts(model: Mapping[str, Any]) -> tuple[str, ...] | None:
+    supported = model.get("supportsEffort")
+    if supported is not None and not isinstance(supported, bool):
+        raise TypeError(_INVALID_RESPONSE)
+    if supported is False:
+        return ()
+    raw_efforts = model.get("supportedEffortLevels")
+    if raw_efforts is None:
+        return None
+    if not isinstance(raw_efforts, list):
+        raise TypeError(_INVALID_RESPONSE)
+    efforts: list[str] = []
+    for effort in cast("list[object]", raw_efforts):
+        if not isinstance(effort, str) or not effort or effort in efforts:
+            raise TypeError(_INVALID_RESPONSE)
+        efforts.append(effort)
+    return tuple(efforts)

shikiru/plugins/agents/claude/options.py

@@ -0,0 +1,62 @@
+"""Claude Code plugin options and protocol constants."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from shikiru.agents.contracts import PERCENT, BillingMode
+from shikiru.plugins.agents.shared_settings import (
+    billing_declaration_setting,
+    cli_args_setting,
+    compact_threshold_setting,
+)
+
+if TYPE_CHECKING:
+    from shikiru.agents.settings import AgentSetting
+
+CLAUDE_COMMAND = "claude"
+PRINT_FLAG = "-p"
+INPUT_FORMAT_FLAG = "--input-format"
+OUTPUT_FORMAT_FLAG = "--output-format"
+STREAM_JSON_FORMAT = "stream-json"
+VERBOSE_FLAG = "--verbose"
+NO_SESSION_PERSISTENCE_FLAG = "--no-session-persistence"
+SAFE_MODE_FLAG = "--safe-mode"
+STRICT_MCP_CONFIG_FLAG = "--strict-mcp-config"
+MCP_CONFIG_FLAG = "--mcp-config"
+EMPTY_MCP_CONFIG = '{"mcpServers":{}}'
+TOOLS_FLAG = "--tools"
+EMPTY_TOOLS = ""
+MODEL_CATALOG_REQUEST_ID = "shikiru-model-catalog"
+DEFAULT_COMPACT_AT_PCT = 80.0
+STATUS_PAYMENT_REQUIRED = 402
+STATUS_TOO_MANY_REQUESTS = 429
+STATUS_UNAUTHORIZED = 401
+STATUS_FORBIDDEN = 403
+PERMISSION_MODE_FLAG = "--permission-mode"
+DEFAULT_ARGS = (PERMISSION_MODE_FLAG, "bypassPermissions")
+SESSION_ID_FLAG = "--session-id"
+RESUME_FLAG = "--resume"
+MODEL_FLAG = "--model"
+EFFORT_FLAG = "--effort"
+ADD_DIR_FLAG = "--add-dir"
+SETTINGS_FLAG = "--settings"
+
+
+class ClaudeOptions(BaseModel):
+    """Options accepted by the Claude Code agent factory."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    args: list[str] = Field(default_factory=lambda: list(DEFAULT_ARGS))
+    compact_at_pct: float = Field(default=DEFAULT_COMPACT_AT_PCT, ge=0, le=PERCENT)
+    billing_mode: BillingMode | None = None
+
+
+CLAUDE_SETTINGS: tuple[AgentSetting, ...] = (
+    compact_threshold_setting(DEFAULT_COMPACT_AT_PCT),
+    billing_declaration_setting(),
+    cli_args_setting(DEFAULT_ARGS),
+)