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

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:

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:

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

Step 5: Tool restriction enforcement

Two separate questions, answered in two places. Read docs/tool-restrictions.md for full context.

How CAO delivers the policy (one of three mechanisms):

• CLI flags (e.g., Claude Code --disallowedTools, Copilot CLI --deny-tool, Grok --allow/--deny): add the provider to TOOL_MAPPING in src/cli_agent_orchestrator/utils/tool_mapping.py to translate CAO vocabulary to native tool names.
• Agent file (e.g., Kiro CLI, OpenCode CLI): CAO writes allowedTools into the agent file at install time in its own vocabulary or the CLI's permission schema. No TOOL_MAPPING entry needed.
• System prompt (e.g., Kimi CLI, Codex): CAO prepends restriction instructions to the system prompt. No TOOL_MAPPING entry needed.

Whether the CLI then enforces it is a separate fact, recorded per provider in src/cli_agent_orchestrator/utils/enforcement.py (native, prompt, none) and shown to the operator on the launch gate. The mechanism does not decide it: OpenCode enforces its agent-file permission block (native, at install time), while Kiro is launched --trust-all-tools with tools: ["*"] and its allowedTools only suppresses approval prompts (none). Adding a provider means adding BOTH its delivery code and its PROVIDER_ENFORCEMENT row; test/test_enforcement_tables.py fails until the docs tables agree.

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