steerdev 1.1.61__tar.gz → 1.1.62__tar.gz

steerdev-1.1.62/AGENTS.md

@@ -0,0 +1,122 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Overview
+
+**steerdev-agent** is a Python CLI that orchestrates AI coding agents via subprocess execution, streaming events to the steerdev.com API. It fetches tasks, builds prompts, launches agents (Claude Code and pi are wired; `openai-codex` is a stub), and reports activity.
+
+## Project Structure
+
+```
+src/steerdev_agent/
+├── cli.py               # Typer CLI commands
+├── runner.py             # Main orchestrator
+├── agent_loop.py         # Persistent agent mode
+├── version.py            # Version management
+├── integration.py        # Integration utilities
+├── api/                  # API clients (tasks, sessions, events, workflows, etc.)
+├── config/               # Pydantic config models and settings
+├── executor/             # Agent subprocess execution (base, claude, stream)
+├── workflow/             # Multi-phase workflow execution and memory
+├── prompt/               # Prompt building and templates
+├── setup/                # Project setup and templates
+├── handlers/             # Task/PRD handlers
+└── git/                  # Git utilities
+```
+
+## Development
+
+- **Python 3.12+** with **uv** package manager
+- `uv sync` — install deps
+- `uv run pytest` — run tests
+- `uv run ruff check . && uv run ruff format .` — lint and format
+- `uv run basedpyright` — type check
+
+## Conventions
+
+- Type hints on all function signatures
+- Pydantic v2 for data models and config
+- Async/await for I/O (HTTP, subprocess)
+- `loguru` for logging
+- Specific exception classes (no bare `except`)
+- Absolute imports (`from steerdev_agent.config.models import ...`)
+- Import order: stdlib, third-party, local
+
+## Key Integration Points
+
+- **steerdev.com API**: Bearer auth via `STEERDEV_API_KEY`. Events POSTed to `/api/v1/sessions/{id}/events`.
+- **Executor**: Launches agents as subprocesses with `--output-format stream-json`. Parses newline-delimited JSON events.
+- **Config**: YAML config file + environment variable overrides.
+
+## Environment Variables
+
+| Variable | Purpose |
+| --- | --- |
+| `STEERDEV_API_KEY` | API authentication |
+| `STEERDEV_PROJECT_ID` | Default project |
+| `STEERDEV_PROVIDER` | Harness provider: `claude` (default), `pi`, `openai-codex`, `acp:<agent>` |
+| `STEERDEV_ACP_HARNESS` | ACP agent name when the provider is bare `acp` (equivalent to `--acp-agent`) |
+| `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY` | Claude credentials (sandbox-injected; locally use `claude login` instead) |
+| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OPENROUTER_API_KEY` / `GEMINI_API_KEY` | pi credentials — whichever matches the selected model's provider (sandbox-injected; locally use `pi` + `/login`) |
+| `OPENAI_API_KEY` | Codex credentials for `openai-codex` (sandbox-injected) |
+| Per-harness (e.g. `GEMINI_API_KEY` for `acp:gemini`) | ACP credentials — declared per agent in the registry (`credential_env`) |
+
+## Providers
+
+The agent supports multiple harness providers via `--provider` (or `STEERDEV_PROVIDER`):
+
+```bash
+steerdev run --provider claude --project-id abc123        # default (Claude Code)
+steerdev run --provider pi --project-id abc123            # pi.dev coding agent
+steerdev run --provider acp:gemini --project-id abc123    # any ACP harness (Gemini CLI here)
+steerdev run --provider openai-codex --project-id abc123  # stub (not yet wired)
+```
+
+`claude` (Claude Code) and `pi` (the [pi.dev](https://pi.dev) coding agent) are
+wired end-to-end. `pi` is launched headless as `pi --mode json "<prompt>"`, with
+resume via `--session`, model via `--model`, and tool allow/deny lists via
+`--tools`/`--exclude-tools`; see `executor/pi.py` and `executor/pi_stream.py`.
+`openai-codex` is a clearly-stubbed seam (`executor/codex.py`) that fails fast
+with a "not yet supported" message.
+
+### ACP harnesses (`acp:<agent>`)
+
+`acp:<agent>` drives **any** harness speaking the
+[Agent Client Protocol](https://agentclientprotocol.com) (JSON-RPC 2.0 over
+stdio) through a single executor — steerdev acts as the ACP *Client*
+(filesystem, terminals, permissions) and the harness is the ACP *Agent*.
+Built-in registry entries (`executor/acp_registry.py`): `acp:gemini`
+(Gemini CLI via `gemini --experimental-acp`), `acp:claude-code` (via
+`npx @zed-industries/claude-code-acp`), `acp:goose` (`goose acp`).
+
+Adding a new harness requires **no code** — declare it under `acp.agents` in
+`steerdev.yaml`:
+
+```yaml
+acp:
+  # default agent for `--provider acp`
+  agent: gemini
+  # auto_approve_all (default) | auto_approve_workdir | read_only | escalate
+  permission_policy: auto_approve_all
+  agents:
+    myagent:
+      name: myagent
+      command: my-acp-agent
+      args: ["--serve"]
+      credential_env: ["MY_AGENT_API_KEY"]
+```
+
+Key modules: `executor/acp.py` (`ACPExecutor` — spawn, initialize,
+session/new|load, prompt), `executor/acp_client.py` (`SteerdevAcpClient` +
+`AcpPermissionPolicy` — fs/terminal/permission callbacks), `executor/acp_stream.py`
+(ACP `session/update` → canonical `EventType` translation), `executor/acp_spec.py`
++ `executor/acp_registry.py` (declarative launch specs). ACP turns end with a
+`stopReason`, not an exit code — `wait()` synthesizes one (nonzero only on
+refusal/error).
+
+Credentials arrive via ENV (the sandbox bootstrap injects them); the agent never
+fetches credentials itself. For providers with a persisted local login (`claude`,
+`pi`, and ACP agents with `requires_local_login`) a missing credential env var
+only warns; for the rest the matching env var must be present or the command
+hard-fails.

{steerdev-1.1.61 → steerdev-1.1.62}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerdev
-Version: 1.1.61
+Version: 1.1.62
 Summary: Backend task runner for steerdev.com - orchestrates CLI coding agents with activity reporting
 Project-URL: Homepage, https://github.com/pentoai/steerdev-agent
 Project-URL: Repository, https://github.com/pentoai/steerdev-agent
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Terminals
 Requires-Python: >=3.12
+Requires-Dist: agent-client-protocol<0.11,>=0.10
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: pydantic-settings>=2.0.0
@@ -43,7 +44,7 @@ Task runner for [steerdev.com](https://steerdev.com) — orchestrates AI coding
 
 ## What It Does
 
-SteerDev Agent connects your AI coding agent (Claude Code, Codex, Aider) to the steerdev.com platform:
+SteerDev Agent connects your AI coding agent (Claude Code or pi; `openai-codex` is a stub) to the steerdev.com platform:
 
 1. **Fetches tasks** from your SteerDev project
 2. **Builds prompts** with project context, task details, and workflow instructions
@@ -299,7 +300,7 @@ api:
   project_id_env: STEERDEV_PROJECT_ID
 
 executor:
-  type: claude               # claude, codex, aider
+  type: claude               # claude (wired), pi (wired), openai-codex (stub)
   permission_mode: default
   allowed_tools: []
   disallowed_tools: []
@@ -316,8 +317,30 @@ worktrees:
 | `STEERDEV_API_KEY` | API key for steerdev.com |
 | `STEERDEV_PROJECT_ID` | Default project ID |
 | `STEERDEV_AGENT_NAME` | Agent name for session tracking |
+| `STEERDEV_PROVIDER` | Harness provider: `claude` (default), `pi`, `openai-codex` |
+| `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY` | Claude credentials (sandbox-injected; locally use `claude login`) |
+| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OPENROUTER_API_KEY` / `GEMINI_API_KEY` | pi credentials — whichever matches the selected model's provider (sandbox-injected; locally use `pi` + `/login`) |
+| `OPENAI_API_KEY` | Codex credentials for `openai-codex` (sandbox-injected) |
 
-> **Note:** CLI agents (Claude Code, Codex, etc.) must be logged in independently before running steerdev. No LLM API keys are needed here.
+> **Note:** Locally, CLI agents like Claude Code and pi can be logged in
+> independently (`claude login`, or `pi` + `/login`) before running steerdev — no
+> LLM API keys are strictly needed. In a sandbox, the bootstrap injects the
+> per-provider credentials above; steerdev never fetches credentials itself.
+
+### Providers
+
+Select the harness with `--provider` (or `STEERDEV_PROVIDER`). Defaults to `claude`:
+
+```bash
+steerdev run --provider claude --project-id YOUR_PROJECT_ID  # Claude Code
+steerdev run --provider pi --project-id YOUR_PROJECT_ID       # pi.dev coding agent
+```
+
+`claude` (Claude Code) and `pi` (the [pi.dev](https://pi.dev) coding agent) are
+wired end-to-end. `pi` runs headless as `pi --mode json "<prompt>"` and streams
+its JSON events back to steerdev. `openai-codex` is a clearly-stubbed seam that
+fails fast with a "not yet supported" message, reserved for a future harness
+protocol.
 
 ## Architecture
 

{steerdev-1.1.61 → steerdev-1.1.62}/README.md

@@ -6,7 +6,7 @@ Task runner for [steerdev.com](https://steerdev.com) — orchestrates AI coding
 
 ## What It Does
 
-SteerDev Agent connects your AI coding agent (Claude Code, Codex, Aider) to the steerdev.com platform:
+SteerDev Agent connects your AI coding agent (Claude Code or pi; `openai-codex` is a stub) to the steerdev.com platform:
 
 1. **Fetches tasks** from your SteerDev project
 2. **Builds prompts** with project context, task details, and workflow instructions
@@ -262,7 +262,7 @@ api:
   project_id_env: STEERDEV_PROJECT_ID
 
 executor:
-  type: claude               # claude, codex, aider
+  type: claude               # claude (wired), pi (wired), openai-codex (stub)
   permission_mode: default
   allowed_tools: []
   disallowed_tools: []
@@ -279,8 +279,30 @@ worktrees:
 | `STEERDEV_API_KEY` | API key for steerdev.com |
 | `STEERDEV_PROJECT_ID` | Default project ID |
 | `STEERDEV_AGENT_NAME` | Agent name for session tracking |
+| `STEERDEV_PROVIDER` | Harness provider: `claude` (default), `pi`, `openai-codex` |
+| `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY` | Claude credentials (sandbox-injected; locally use `claude login`) |
+| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OPENROUTER_API_KEY` / `GEMINI_API_KEY` | pi credentials — whichever matches the selected model's provider (sandbox-injected; locally use `pi` + `/login`) |
+| `OPENAI_API_KEY` | Codex credentials for `openai-codex` (sandbox-injected) |
 
-> **Note:** CLI agents (Claude Code, Codex, etc.) must be logged in independently before running steerdev. No LLM API keys are needed here.
+> **Note:** Locally, CLI agents like Claude Code and pi can be logged in
+> independently (`claude login`, or `pi` + `/login`) before running steerdev — no
+> LLM API keys are strictly needed. In a sandbox, the bootstrap injects the
+> per-provider credentials above; steerdev never fetches credentials itself.
+
+### Providers
+
+Select the harness with `--provider` (or `STEERDEV_PROVIDER`). Defaults to `claude`:
+
+```bash
+steerdev run --provider claude --project-id YOUR_PROJECT_ID  # Claude Code
+steerdev run --provider pi --project-id YOUR_PROJECT_ID       # pi.dev coding agent
+```
+
+`claude` (Claude Code) and `pi` (the [pi.dev](https://pi.dev) coding agent) are
+wired end-to-end. `pi` runs headless as `pi --mode json "<prompt>"` and streams
+its JSON events back to steerdev. `openai-codex` is a clearly-stubbed seam that
+fails fast with a "not yet supported" message, reserved for a future harness
+protocol.
 
 ## Architecture
 

{steerdev-1.1.61 → steerdev-1.1.62}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steerdev"
-version = "1.1.61"
+version = "1.1.62"
 description = "Backend task runner for steerdev.com - orchestrates CLI coding agents with activity reporting"
 readme = "README.md"
 authors = [
@@ -28,6 +28,7 @@ dependencies = [
     "pyyaml>=6.0.0",
     "python-dotenv>=1.2.1",
     "tenacity>=9.0.0",
+    "agent-client-protocol>=0.10,<0.11",
 ]
 
 [project.optional-dependencies]

{steerdev-1.1.61 → steerdev-1.1.62}/src/steerdev_agent/agent_loop.py

@@ -46,6 +46,7 @@ from steerdev_agent.config.models import (
     WorktreeConfig,
 )
 from steerdev_agent.executor import ExecutorFactory
+from steerdev_agent.executor.acp_registry import application_for_agent_type
 from steerdev_agent.executor.base import EventType
 from steerdev_agent.executor.claude import ClaudeExecutorError
 
@@ -747,7 +748,7 @@ class AgentLoop(CommandExecutor):
                     json={
                         "name": self.agent_name,
                         "project_id": self.project_id,
-                        "application": self.agent_type,
+                        "application": application_for_agent_type(self.agent_type),
                         "hostname": socket.gethostname(),
                     },
                 )
@@ -917,7 +918,7 @@ class AgentLoop(CommandExecutor):
                     json={
                         "name": self.agent_name,
                         "project_id": self.project_id,
-                        "application": self.agent_type,
+                        "application": application_for_agent_type(self.agent_type),
                         "hostname": socket.gethostname(),
                     },
                 )
@@ -1152,7 +1153,7 @@ class WorkspaceAgentLoop(CommandExecutor):
         try:
             result = await agents_client.register_workspace(
                 name=self.agent_name,
-                application=self.agent_type,
+                application=application_for_agent_type(self.agent_type),
                 hostname=socket.gethostname(),
                 workspace_path=str(self.workspace_path),
                 capabilities=detect_installed_tools(),
@@ -1355,7 +1356,7 @@ class WorkspaceAgentLoop(CommandExecutor):
         try:
             await agents_client.register_workspace(
                 name=self.agent_name,
-                application=self.agent_type,
+                application=application_for_agent_type(self.agent_type),
                 hostname=socket.gethostname(),
                 workspace_path=str(self.workspace_path),
                 capabilities=detect_installed_tools(),

{steerdev-1.1.61 → steerdev-1.1.62}/src/steerdev_agent/api/tasks.py

@@ -468,11 +468,12 @@ class TasksClient(SteerDevClient):
             payload["actual_files"] = actual_files
         if predicted_files is not None:
             payload["predicted_files"] = predicted_files
-        payload["source"] = "agent_reported"
 
         if not payload:
             return False
 
+        payload["source"] = "agent_reported"
+
         response = self.patch(f"/tasks/{task_id}/files", json=payload)
         if response.status_code not in (200, 204):
             logger.warning(f"Failed to report files for task {task_id}: {response.status_code}")

{steerdev-1.1.61 → steerdev-1.1.62}/src/steerdev_agent/cli.py

@@ -13,7 +13,11 @@ from loguru import logger
 from rich.console import Console
 from rich.panel import Panel
 
-from steerdev_agent.config.models import SteerDevConfig
+from steerdev_agent.config.models import (
+    SUPPORTED_PROVIDERS,
+    SteerDevConfig,
+    is_supported_provider,
+)
 from steerdev_agent.update_check import check_for_update
 from steerdev_agent.version import get_version
 
@@ -22,6 +26,133 @@ console = Console()
 # Load environment variables from .env file in current working directory
 load_dotenv(Path.cwd() / ".env", override=True)
 
+# ============================================================================
+# Provider (harness) resolution helpers
+# ============================================================================
+# Candidate credential env vars per provider, in priority order. The sandbox
+# bootstrap injects these; the agent never fetches credentials itself. For
+# providers that support a persisted local login (claude, pi), a missing env
+# var only warns; for the rest it hard-fails.
+PROVIDER_CREDENTIAL_ENV: dict[str, tuple[str, ...]] = {
+    "claude": ("CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY"),
+    "pi": ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENROUTER_API_KEY", "GEMINI_API_KEY"),
+    "openai-codex": ("OPENAI_API_KEY",),
+}
+
+# Providers whose CLI can fall back to a persisted local login session, so a
+# missing credential env var is a warning rather than a hard failure.
+LOCAL_LOGIN_PROVIDERS: dict[str, str] = {
+    "claude": "claude login",
+    "pi": "pi (then /login)",
+}
+
+
+def _resolve_provider(cli_value: str | None, config: SteerDevConfig) -> str:
+    """Resolve the harness provider with precedence flag > env > config > default.
+
+    Args:
+        cli_value: Value of the ``--provider`` option (None if not passed).
+        config: Loaded SteerDev configuration.
+
+    Returns:
+        The resolved provider identifier (defaults to "claude").
+    """
+    if cli_value:
+        return cli_value
+    env_value = os.environ.get("STEERDEV_PROVIDER")
+    if env_value:
+        return env_value
+    if config.executor.type:
+        return config.executor.type
+    return "claude"
+
+
+def _resolve_acp_provider(provider: str, acp_agent: str | None, config: SteerDevConfig) -> str:
+    """Normalize a bare ``acp`` provider to the full ``acp:<agent>`` form.
+
+    Args:
+        provider: The resolved provider identifier.
+        acp_agent: Value of the ``--acp-agent`` option (None if not passed).
+        config: Loaded SteerDev configuration.
+
+    Returns:
+        The provider with the ACP agent name attached when applicable.
+
+    Raises:
+        typer.Exit: If the ACP provider has no agent name to resolve.
+    """
+    if provider != "acp":
+        return provider
+    agent_name = acp_agent or config.acp.agent
+    if not agent_name:
+        console.print(
+            "[red]Error: provider 'acp' requires an agent name. Use "
+            "--provider acp:<agent> (e.g. acp:gemini), pass --acp-agent, or "
+            "set acp.agent in the config.[/red]"
+        )
+        raise typer.Exit(1)
+    return f"acp:{agent_name}"
+
+
+def _check_provider_credentials(provider: str, config: SteerDevConfig | None = None) -> None:
+    """Validate that credentials for a provider are present in the environment.
+
+    Providers that support a persisted local login (``claude``, ``pi`` — see
+    ``LOCAL_LOGIN_PROVIDERS``; ACP harnesses via ``requires_local_login``) only
+    warn when no candidate env var is set, so a local login session keeps
+    working. Other providers (e.g. ``openai-codex``) hard-fail.
+
+    Args:
+        provider: The resolved provider identifier.
+        config: Loaded configuration (for ACP registry overrides).
+
+    Raises:
+        typer.Exit: If a provider without a local-login fallback has no
+            credentials in the environment.
+    """
+    candidates = PROVIDER_CREDENTIAL_ENV.get(provider, ())
+    local_login_hint = LOCAL_LOGIN_PROVIDERS.get(provider)
+
+    # ACP providers carry their credential contract in the harness spec.
+    if provider.startswith("acp:"):
+        from steerdev_agent.executor.acp_registry import (
+            acp_harness_from_provider,
+            resolve_acp_spec,
+        )
+
+        harness = acp_harness_from_provider(provider)
+        overrides = config.acp.agents if config else None
+        try:
+            spec = resolve_acp_spec(harness or "", overrides)
+        except ValueError as e:
+            console.print(f"[red]Error: {e}[/red]")
+            raise typer.Exit(1) from e
+        candidates = tuple(spec.credential_env)
+        if spec.requires_local_login:
+            local_login_hint = spec.local_login_hint or spec.command
+
+    has_credential = any(os.environ.get(var) for var in candidates)
+    if has_credential:
+        return
+
+    if local_login_hint is not None:
+        vars_list = " or ".join(candidates) if candidates else "(none configured)"
+        console.print(
+            f"[yellow]Warning: no credentials for '{provider}' in the environment "
+            f"({vars_list}). Relying on a local `{local_login_hint}` "
+            f"session.[/yellow]"
+        )
+        return
+
+    vars_list = " or ".join(candidates) if candidates else "(none configured)"
+    console.print(
+        f"[red]Error: provider '{provider}' requires credentials in the "
+        f"environment. Set {vars_list} (the sandbox bootstrap normally injects "
+        f"these).[/red]"
+    )
+    raise typer.Exit(1)
+
+
 app = typer.Typer(
     name="steerdev",
     help="Backend task runner for steerdev.com - orchestrates CLI coding agents",
@@ -1614,18 +1745,6 @@ def run(
             envvar="STEERDEV_AGENT_ID",
         ),
     ] = None,
-    provider: Annotated[
-        str | None,
-        typer.Option(
-            "--provider",
-            help=(
-                "AI provider / executor type to run tasks with (e.g. claude)."
-                " Overrides steerdev.yaml executor.type."
-                " Reads from STEERDEV_PROVIDER env var."
-            ),
-            envvar="STEERDEV_PROVIDER",
-        ),
-    ] = None,
     model: Annotated[
         str | None,
         typer.Option(
@@ -1769,6 +1888,22 @@ def run(
             ),
         ),
     ] = None,
+    provider: Annotated[
+        str | None,
+        typer.Option(
+            "--provider",
+            help="Harness provider: claude | pi | openai-codex | acp:<agent> (default: claude)",
+            envvar="STEERDEV_PROVIDER",
+        ),
+    ] = None,
+    acp_agent: Annotated[
+        str | None,
+        typer.Option(
+            "--acp-agent",
+            help="ACP agent name when --provider is 'acp' (e.g. gemini, claude-code, goose)",
+            envvar="STEERDEV_ACP_HARNESS",
+        ),
+    ] = None,
 ) -> None:
     """Run the agent for a project!
 
@@ -1855,6 +1990,23 @@ def run(
         f"canals={merge_flags.enable_canals} ({merge_flags.canals_source})"
     )
 
+    # Resolve provider: CLI flag > STEERDEV_PROVIDER env > config > default.
+    resolved_provider = _resolve_provider(provider, config)
+    resolved_provider = _resolve_acp_provider(resolved_provider, acp_agent, config)
+    if not is_supported_provider(resolved_provider):
+        supported = ", ".join((*SUPPORTED_PROVIDERS, "acp:<agent>"))
+        console.print(
+            f"[red]Error: unsupported provider '{resolved_provider}'. Supported: {supported}.[/red]"
+        )
+        raise typer.Exit(1)
+    resolved_executor_config = config.executor.model_copy(
+        update={
+            "type": resolved_provider,
+            "acp_agents": config.acp.agents,
+            "acp_permission_policy": config.acp.permission_policy,
+        }
+    )
+
     worktree_status = (
         f"enabled ({resolved_worktree_config.provider})"
         if resolved_worktree_config.enabled
@@ -1879,6 +2031,7 @@ def run(
             f"[bold blue]SteerDev Agent[/bold blue]\n"
             f"Project ID: {resolved_project_id}\n"
             f"Agent Name: {agent_name_display}\n"
+            f"Provider: {resolved_provider}\n"
             f"Working Directory: {working_dir or 'current'}\n"
             f"Provider: {resolved_executor_config.type}\n"
             f"Model: {resolved_model or 'default'}\n"
@@ -1912,12 +2065,28 @@ def run(
     if default_branch is not None:
         resolved_branch_config.default_branch = default_branch
 
+    # Preflight provider checks (skip in dry-run so command preview works offline).
+    if not dry_run:
+        from steerdev_agent.workspace.tool_detection import (
+            cli_for_provider,
+            is_provider_cli_available,
+        )
+
+        _check_provider_credentials(resolved_provider, config)
+        if not is_provider_cli_available(resolved_provider, config.acp.agents):
+            console.print(
+                f"[red]Error: CLI '{cli_for_provider(resolved_provider, config.acp.agents)}' "
+                f"for provider '{resolved_provider}' not found in PATH.[/red]"
+            )
+            raise typer.Exit(1)
+
     try:
         result = asyncio.run(
             run_agent(
                 project_id=resolved_project_id,
                 working_directory=str(working_dir) if working_dir else None,
                 api_key=resolved_api_key,
+                agent_type=resolved_provider,
                 agent_name=agent_name,
                 model=resolved_model,
                 max_turns=resolved_max_turns,
@@ -2106,6 +2275,22 @@ def agent(
             help="Default branch for sync/rebase/PR targets (default: from config or 'main')",
         ),
     ] = None,
+    provider: Annotated[
+        str | None,
+        typer.Option(
+            "--provider",
+            help="Harness provider: claude | pi | openai-codex | acp:<agent> (default: claude)",
+            envvar="STEERDEV_PROVIDER",
+        ),
+    ] = None,
+    acp_agent: Annotated[
+        str | None,
+        typer.Option(
+            "--acp-agent",
+            help="ACP agent name when --provider is 'acp' (e.g. gemini, claude-code, goose)",
+            envvar="STEERDEV_ACP_HARNESS",
+        ),
+    ] = None,
 ) -> None:
     """Run the agent in persistent mode.
 
@@ -2188,6 +2373,37 @@ def agent(
     if default_branch is not None:
         resolved_branch_config.default_branch = default_branch
 
+    # Resolve provider: CLI flag > STEERDEV_PROVIDER env > config > default.
+    resolved_provider = _resolve_provider(provider, config)
+    resolved_provider = _resolve_acp_provider(resolved_provider, acp_agent, config)
+    if not is_supported_provider(resolved_provider):
+        supported = ", ".join((*SUPPORTED_PROVIDERS, "acp:<agent>"))
+        console.print(
+            f"[red]Error: unsupported provider '{resolved_provider}'. Supported: {supported}.[/red]"
+        )
+        raise typer.Exit(1)
+    resolved_executor_config = config.executor.model_copy(
+        update={
+            "type": resolved_provider,
+            "acp_agents": config.acp.agents,
+            "acp_permission_policy": config.acp.permission_policy,
+        }
+    )
+
+    # Preflight provider checks (agent mode always launches real subprocesses).
+    from steerdev_agent.workspace.tool_detection import (
+        cli_for_provider,
+        is_provider_cli_available,
+    )
+
+    _check_provider_credentials(resolved_provider, config)
+    if not is_provider_cli_available(resolved_provider, config.acp.agents):
+        console.print(
+            f"[red]Error: CLI '{cli_for_provider(resolved_provider, config.acp.agents)}' "
+            f"for provider '{resolved_provider}' not found in PATH.[/red]"
+        )
+        raise typer.Exit(1)
+
     # Resolve workspace path: CLI > config
     resolved_workspace = workspace or config.workspace.workspace_dir
 
@@ -2217,12 +2433,13 @@ def agent(
             asyncio.run(
                 run_workspace_agent_loop(
                     workspace_path=str(resolved_workspace),
+                    agent_type=resolved_provider,
                     agent_name=agent_name,
                     api_key=resolved_api_key,
                     model=resolved_model,
                     max_turns=resolved_max_turns,
                     agent_loop_config=agent_loop_config,
-                    executor_config=config.executor,
+                    executor_config=resolved_executor_config,
                     workspace_config=config.workspace,
                     force_workflow_id=workflow_id,
                     enable_waves=merge_flags.enable_waves,
@@ -2273,13 +2490,14 @@ def agent(
             asyncio.run(
                 run_agent_loop(
                     project_id=resolved_project_id,
+                    agent_type=resolved_provider,
                     agent_name=agent_name,
                     working_directory=str(working_dir) if working_dir else None,
                     api_key=resolved_api_key,
                     model=resolved_model,
                     max_turns=resolved_max_turns,
                     agent_loop_config=agent_loop_config,
-                    executor_config=config.executor,
+                    executor_config=resolved_executor_config,
                     force_workflow_id=resolved_workflow_id,
                     enable_waves=merge_flags.enable_waves,
                     enable_canals=merge_flags.enable_canals,