feat: --cli-arg and --cli-args (#19)

Author: Gusarich

README.md

@@ -96,6 +96,33 @@ Override Docker image
 pitaya "task" --plugin codex --docker-image ghcr.io/me/codex-cli:mytag
 ```
 
+Agent CLI passthrough
+
+Forward raw arguments directly to the underlying agent CLI (Codex or Claude). This is useful for advanced flags or experimental options exposed by the tools.
+
+```bash
+# Single tokens (repeatable)
+pitaya "fix bug" --plugin codex \
+  --cli-arg -c \
+  --cli-arg 'feature_flag=true' \
+  --cli-arg --no-color
+
+# Quoted list (recommended for ordered sequences)
+pitaya "refactor module" --plugin codex \
+  --cli-args '-c model="gpt-4o-mini" --dry-run -v'
+
+# Mix-and-match
+pitaya "task" --plugin claude-code \
+  --cli-arg --verbose \
+  --cli-args '--max-turns 8'
+```
+
+Notes
+
+- Passthrough args are inserted before the final prompt position.
+- `--cli-args` uses POSIX shlex splitting; quote values that contain spaces.
+- If both forms are provided, Pitaya combines all `--cli-arg` tokens followed by tokens from `--cli-args`. For strict ordering, prefer a single `--cli-args` string.
+
 Resume a run
 
 ```bash

src/cli.py

@@ -157,6 +157,20 @@ def create_parser(cls) -> argparse.ArgumentParser:
             type=str,
             help="Override Docker image (e.g., myrepo/custom:tag)",
         )
+        # Agent CLI passthrough
+        g_model.add_argument(
+            "--cli-arg",
+            action="append",
+            dest="agent_cli_arg",
+            metavar="ARG",
+            help="Pass-through single argument to the agent CLI (repeatable)",
+        )
+        g_model.add_argument(
+            "--cli-args",
+            dest="agent_cli_args_str",
+            metavar="'ARGS'",
+            help="Quoted list of arguments to pass to the agent CLI (e.g., --cli-args '-c key=\"v\" --flag')",
+        )
 
         # Repository group
         g_repo = parser.add_argument_group("Repository")
@@ -1876,6 +1890,20 @@ def _red(k, v):
 
         # Proxy automatic egress defaults removed
 
+        # Combine agent CLI passthrough args and create orchestrator
+        try:
+            import shlex as _shlex
+
+            _agent_cli_args: list[str] = []
+            if getattr(args, "agent_cli_arg", None):
+                _agent_cli_args.extend(
+                    [str(a) for a in args.agent_cli_arg if a is not None]
+                )
+            if getattr(args, "agent_cli_args_str", None):
+                _agent_cli_args.extend(_shlex.split(str(args.agent_cli_args_str)))
+        except Exception:
+            _agent_cli_args = []
+
         # Create orchestrator
         self.orchestrator = Orchestrator(
             max_parallel_instances=max_parallel_val,
@@ -1936,6 +1964,7 @@ def _red(k, v):
                 full_config.get("model", getattr(args, "model", "sonnet"))
             ),
             default_docker_image=full_config.get("runner", {}).get("docker_image"),
+            default_agent_cli_args=_agent_cli_args or None,
         )
 
         # Initialize orchestrator

src/instance_runner/api.py

@@ -54,6 +54,7 @@ async def run_instance(
     model_mapping_checksum: Optional[str] = None,
     allow_overwrite_protected_refs: bool = False,
     allow_global_session_volume: bool = False,
+    agent_cli_args: Optional[list[str]] = None,
 ) -> InstanceResult:
     """
     Execute a single AI coding instance in an isolated environment.
@@ -131,6 +132,7 @@ async def run_instance(
         model_mapping_checksum=model_mapping_checksum,
         allow_overwrite_protected_refs=allow_overwrite_protected_refs,
         allow_global_session_volume=allow_global_session_volume,
+        agent_cli_args=agent_cli_args,
     )
 
 

src/instance_runner/plugins/claude_code.py

@@ -145,6 +145,14 @@ async def build_command(
         if "append_system_prompt" in kwargs and kwargs["append_system_prompt"]:
             command.extend(["--append-system-prompt", kwargs["append_system_prompt"]])
 
+        # Add passthrough CLI args, if any
+        try:
+            extra_args = kwargs.get("agent_cli_args") or []
+            if isinstance(extra_args, (list, tuple)):
+                command.extend([str(x) for x in extra_args if x is not None])
+        except Exception:
+            pass
+
         # Always pass the prompt when provided. On resume, Orchestrator supplies
         # a minimal continuation prompt (e.g., "Continue") so the agent keeps going.
         if prompt:

src/instance_runner/plugins/codex.py

@@ -155,6 +155,14 @@ async def build_command(
         if system_prompt:
             cmd += ["--system-prompt", str(system_prompt)]
 
+        # Agent CLI passthrough args: insert before prompt
+        try:
+            extra_args = kwargs.get("agent_cli_args") or []
+            if isinstance(extra_args, (list, tuple)):
+                cmd += [str(x) for x in extra_args if x is not None]
+        except Exception:
+            pass
+
         # Final positional: the prompt
         if prompt:
             cmd.append(prompt)

src/instance_runner/runner.py

@@ -103,6 +103,7 @@ async def run_instance(
     model_mapping_checksum: Optional[str] = None,
     allow_overwrite_protected_refs: bool = False,
     allow_global_session_volume: bool = False,
+    agent_cli_args: Optional[list[str]] = None,
 ) -> InstanceResult:
     """
     Execute a single AI coding instance in Docker.
@@ -257,6 +258,7 @@ async def run_instance(
             max_turns=max_turns,
             allow_overwrite_protected_refs=allow_overwrite_protected_refs,
             allow_global_session_volume=allow_global_session_volume,
+            agent_cli_args=agent_cli_args,
         )
 
         # Success or non-retryable error
@@ -362,6 +364,7 @@ async def _run_instance_attempt(
     max_turns: Optional[int] = None,
     allow_overwrite_protected_refs: bool = False,
     allow_global_session_volume: bool = False,
+    agent_cli_args: Optional[list[str]] = None,
 ) -> InstanceResult:
     """Single attempt at running an instance (internal helper for retry logic)."""
     start_time = time.time()
@@ -646,6 +649,7 @@ def emit_event(event_type: str, data: Dict[str, Any]) -> None:
                 max_turns=max_turns,
                 stream_log_path=log_path,
                 **codex_provider_kwargs,
+                agent_cli_args=(agent_cli_args or []),
             )
 
             agent_session_id = result_data.get("session_id")

src/orchestration/orchestrator.py

@@ -72,6 +72,7 @@ def __init__(
         default_plugin_name: str = "claude-code",
         default_model_alias: str = "sonnet",
         default_docker_image: Optional[str] = None,
+        default_agent_cli_args: Optional[List[str]] = None,
     ):
         """
         Initialize orchestrator.
@@ -98,6 +99,11 @@ def __init__(
         self.default_network_egress = str(default_network_egress or "online").lower()
         # Optional global Docker image override
         self.default_docker_image = default_docker_image
+        # Optional default agent CLI passthrough args
+        try:
+            self.default_agent_cli_args: List[str] = list(default_agent_cli_args or [])
+        except Exception:
+            self.default_agent_cli_args = []
         # Load model mapping checksum for handshake (single-process still validates equality)
         try:
             from ..utils.model_mapping import load_model_mapping
@@ -1741,6 +1747,7 @@ def _write_last_active():
                 model_mapping_checksum=self._models_checksum,
                 allow_overwrite_protected_refs=self.allow_overwrite_protected_refs,
                 allow_global_session_volume=self.allow_global_session_volume,
+                agent_cli_args=(info.metadata or {}).get("agent_cli_args"),
             )
             logger.info(
                 f"_execute_instance: run_instance finished iid={instance_id} success={result.success} status={getattr(result,'status',None)}"
@@ -2681,6 +2688,7 @@ async def _run_instance_from_saved_state(self, instance_info) -> InstanceResult:
                 ),
                 allow_overwrite_protected_refs=self.allow_overwrite_protected_refs,
                 allow_global_session_volume=self.allow_global_session_volume,
+                agent_cli_args=(instance_info.metadata or {}).get("agent_cli_args"),
             )
 
             # Update state

src/orchestration/strategy_context.py

@@ -140,6 +140,14 @@ async def spawn_instance(
             metadata = {}
         metadata["model"] = model
 
+        # Include default agent CLI passthrough args when configured
+        try:
+            _args = getattr(self._orchestrator, "default_agent_cli_args", [])
+            if _args and "agent_cli_args" not in metadata:
+                metadata["agent_cli_args"] = list(_args)
+        except Exception:
+            pass
+
         instance_id = await self._orchestrator.spawn_instance(
             prompt=prompt,
             repo_path=self._orchestrator.repo_path,  # Context knows the repo
@@ -351,6 +359,14 @@ def _drop_nulls(obj):
             ),
         }
 
+        # Include default agent CLI passthrough args when configured
+        try:
+            _args = getattr(self._orchestrator, "default_agent_cli_args", [])
+            if _args and "agent_cli_args" not in _metadata:
+                _metadata["agent_cli_args"] = list(_args)
+        except Exception:
+            pass
+
         # Orchestration-level scheduling retry policy
         max_attempts = 1
         base_s = 0.0