cao-provider

# CAO Provider Creator

Guide for creating a new CLI agent provider for CLI Agent Orchestrator. A "provider" is an adapter that lets CAO interact with a specific CLI-based AI agent through tmux.

## What You're Building

A provider translates between CAO's unified interface and a specific CLI tool's terminal output. It needs to:

1. **Launch** the CLI tool in a tmux window with the right flags
2. **Detect status** by parsing terminal output (IDLE, PROCESSING, COMPLETED, ERROR, WAITING_USER_ANSWER)
3. **Extract responses** from the terminal buffer after the agent finishes
4. **Clean up** when the terminal is deleted

## Before You Start

Gather this information about the target CLI:

- What command launches it? (e.g., `claude`, `kiro-cli chat`, `codex`)
- What does the idle prompt look like? (e.g., `> `, `❯ `, `ask a question`)
- What does the processing state look like? (e.g., spinner characters, "Thinking...")
- How are responses formatted? (e.g., preceded by `⏺`, inside a box, plain text)
- Does it support `--dangerously-skip-permissions` or similar flags?
- Does it have a REPL mode or is it single-shot?
- How does it handle MCP servers? (CLI flags, config file, agent JSON)
- Does it use alt-screen (full-screen TUI) or scrollback (inline output)? This fundamentally changes status detection logic — see lesson #16
- What's the exit command? (`/exit`, `/quit`, Ctrl+C)

## Step-by-Step Implementation

### Step 1: Add to ProviderType enum

File: `src/cli_agent_orchestrator/models/provider.py`

```python
class ProviderType(str, Enum):
    # ... existing providers ...
    NEW_CLI = "new_cli"
```

The value string is used everywhere — in API requests, database, config. Use snake_case.

### Step 2: Create the provider class

File: `src/cli_agent_orchestrator/providers/new_cli.py`

Read `references/provider-template.md` for the full annotated template. The key sections:

**Regex patterns** — Define at module level, not inside methods. You need patterns for:
- ANSI code stripping (reuse `r"\x1b\[[0-9;]*m"`)
- Idle prompt detection (what the prompt looks like when waiting for input)
- Processing detection (spinners, "Thinking...", progress indicators)
- Response markers (how agent responses start — e.g., `⏺` for Claude Code)
- Permission/confirmation prompts (if the CLI asks Y/n questions)

**Status detection priority** — The order in `get_status()` matters. Read `references/lessons-learnt.md` for the critical "stale buffer" lesson. The recommended pattern:

```
1. Strip ANSI codes from terminal output
2. Check WAITING_USER_ANSWER first (permission prompts need immediate attention)
3. Check COMPLETED (response marker + idle prompt both present in recent lines)
4. Check IDLE (just idle prompt, no response marker)
5. Check PROCESSING (spinner/thinking indicator in recent lines only)
6. Default to ERROR
```

**Message extraction** — Find the last response boundary in the terminal output and extract everything between it and the next prompt. Always strip ANSI codes from the final extracted text.

### Step 3: Register in ProviderManager

File: `src/cli_agent_orchestrator/providers/manager.py`

Add the import and elif branch:

```python
from cli_agent_orchestrator.providers.new_cli import NewCliProvider

# In create_provider():
elif provider_type == ProviderType.NEW_CLI.value:
    provider = NewCliProvider(
        terminal_id, tmux_session, tmux_window, agent_profile, allowed_tools
    )
```

### Step 4: Add to PROVIDERS_REQUIRING_WORKSPACE_ACCESS

File: `src/cli_agent_orchestrator/cli/commands/launch.py`

If the provider executes code or accesses the filesystem, add it:

```python
PROVIDERS_REQUIRING_WORKSPACE_ACCESS = {
    # ... existing ...
    "new_cli",
}
```

### Step 5: Tool restriction enforcement

There are three approaches depending on the CLI's capabilities. Read `docs/tool-restrictions.md` for full context.

**Hard enforcement via CLI flags** (e.g., Claude Code, Copilot CLI): Add the provider to `TOOL_MAPPING` in `src/cli_agent_orchestrator/utils/tool_mapping.py` to translate CAO vocabulary to native tool names.

**Hard enforcement via agent JSON** (e.g., Kiro CLI): The CLI reads `allowedTools` from the agent profile. No `TOOL_MAPPING` entry needed — CAO passes vocabulary directly.

**Soft enforcement via system prompt** (e.g., Kimi CLI, Codex): No native restriction mechanism. CAO prepends restriction instructions to the system prompt. No `TOOL_MAPPING` entry needed.

Only add a `TOOL_MAPPING` entry if the CLI has its own native tool names that differ from CAO's vocabulary.

### Step 6: Handle startup prompts

Many CLIs show cascading prompts on first launch (workspace trust, permission bypass, terms acceptance). Handle these in `initialize()` or a dedicated `_handle_startup_prompts()` method using a polling loop — not a single check. See `references/lessons-learnt.md` #17 for the stabilization loop pattern. Also consider shell warm-up (#14) and TERM variable compatibility (#15).

### Step 7: Write unit tests

File: `test/providers/test_new_cli_unit.py`

Read `references/test-guide.md` for the full test structure. Minimum coverage:

1. **Initialization** — successful start, shell timeout, CLI timeout, agent profiles
2. **Status detection** — IDLE, PROCESSING, COMPLETED, WAITING_USER_ANSWER, ERROR, empty output
3. **Message extraction** — successful extraction, edge cases, error handling
4. **Regex patterns** — verify each pattern matches expected terminal output
5. **Edge cases** — ANSI codes, Unicode, long outputs, multiple responses

Use `unittest.mock.patch` to mock `tmux_client`. Create fixture files in `test/providers/fixtures/`.

### Step 8: Write e2e tests

Add test classes to existing e2e test files and a fixture in `test/e2e/conftest.py`. Read `references/test-guide.md` for the full list of e2e test classes to add.

### Step 9: Validate with assign + handoff orchestration

This is the canonical multi-agent e2e test. It exercises assign (non-blocking), handoff (blocking), send_me