[P4.5] Copilot adapter (text-only, degraded) — build + parse + capabilities + tests + docs

[frankbria]

Phase 4 — Provider onboarding. Copilot has NO structured output — the degraded path.

Scope

• lib/agents/copilot.sh:
  • Build: -p/--prompt, -s/--silent (agent response only), --resume [id] /
    --continue, --model, granular --allow-tool/--deny-tool/--allow-all.
  • Parse: TEXT-mode normalize -> internal struct. Exit detection relies entirely on
    the RALPH_STATUS text block; reuse the text-mode heuristics path (Issue Exit confidence threshold (≥40) causes false-positive completions on documentation keywords #224).
  • Capabilities: structured=no, token usage=no, permission_denials=no(but rich perms
    at build time), api_limit=off, session=resume-id.
• This issue validates the graceful-degradation design from [P2.1] under the hardest case.
• Tests via [P2.2]; docs/providers/COPILOT.md (call out reduced feature set); README row.

Acceptance

• ralph --provider copilot drives the loop on text output; token-limit / perm-breaker /
  api-limit features cleanly disabled with logged warnings. Full suite green.

Depends on: [P3.1], [P2.1].

[github-actions]

Triage: Enhancement (feature work)

Categorized this as an enhancement. It's a clearly-scoped implementation task within the multi-provider epic (issues #310–#325): adding lib/agents/copilot.sh as the text-only / degraded provider adapter, with build + parse + capabilities + tests + docs.

Why this category:

• Not a bug — it's net-new provider-adapter functionality, not a defect in existing behavior.
• Not a duplicate — it's the distinct Copilot adapter, separate from the Codex ([P3.1] Codex adapter (pilot) — build + parse + capabilities + tests + docs #317), Gemini ([P4.1] Gemini adapter — build + parse + capabilities + tests + docs #318), OpenCode ([P4.2] OpenCode adapter — build + parse + capabilities + tests + docs #319), Droid ([P4.3] Droid adapter — build + parse + capabilities + tests + docs #320), and Kilocode ([P4.4] Kilocode adapter — build + parse + capabilities + tests + docs #321) adapters in the same phase. It intentionally validates the graceful-degradation design ([P2.1] Capabilities matrix + graceful feature degradation #315) under the hardest case (no structured output).
• Well-specified — has explicit scope, acceptance criteria, and dependencies, so no needs-info is required.

Recommended next steps:

• Resolve dependencies first: [P3.1] Codex pilot ([P3.1] Codex adapter (pilot) — build + parse + capabilities + tests + docs #317, the template adapter) and [P2.1] capabilities/degradation ([P2.1] Capabilities matrix + graceful feature degradation #315). The generic test harness [P2.2] ([P2.2] Generic adapter test harness (mock CLIs) #316) provides the mock-CLI scaffolding for the tests.
• Implement text-mode exit detection via the RALPH_STATUS block, reusing the text-mode heuristics path (Issue Exit confidence threshold (≥40) causes false-positive completions on documentation keywords #224) — that's the portable signal when structured output is unavailable.
• Ensure token-limit, permission-breaker, and api-limit features are cleanly gated off with one-time logged warnings per the capabilities record.

The existing multi-provider epic label is retained.

Note: assignment to @frankbria was reserved for confirmed bugs per the triage rules, so it was not applied here; the issue is already authored/owned within the epic.

Generated by Issue Triage Assistant for issue #322 · opus48 417.8K · ◷

[coderabbitai]

Coding Plan

Summary

• Introduce minimal provider dispatch infrastructure that adds --provider flag routing while preserving Claude as the unchanged default path, avoiding premature abstraction
• Implement lib/agents/copilot.sh with command building, capability declaration, and degraded-feature warning logging
• Leverage existing text-mode parsing infrastructure in response_analyzer.sh (RALPH_STATUS detection, Issue #224 heuristics) rather than creating new parsing code
• Follow established test patterns (bats, mock recording) and documentation structure to ensure consistency with existing codebase

Design Choices

Design Choice 1: Copilot CLI Binary and Interface

Options Considered:

1. Assume copilot as the binary name with configurable COPILOT_CODE_CMD environment variable
2. Use gh copilot (GitHub CLI extension) as the binary

Chosen Option: 1

Rationale: Parallels the existing CLAUDE_CODE_CMD pattern and allows flexibility for different Copilot CLI installations.

Design Choice 2: Provider Abstraction Scope

Options Considered:

1. Create full provider abstraction with Claude refactored into an adapter
2. Create minimal dispatch infrastructure that preserves Claude as default while adding Copilot as an alternative path
3. Block this ticket until P2.1/P3.1 are complete

Chosen Option: 2

Rationale: Delivers the ticket requirements without over-engineering. Claude behavior remains unchanged (no refactor risk), while Copilot gets its own parallel path. Future P3.1 work can refactor Claude into an adapter.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Provider Dispatch Infrastructure

Add minimal infrastructure to support --provider flag routing while preserving existing Claude behavior as the default path. This creates the foundation the Copilot adapter plugs into.

Task 1: Add Provider CLI Flag

Add --provider argument parsing to the CLI options section of ralph_loop.sh and establish the AGENT_PROVIDER variable with claude as the default.

• Add --provider to the argument parsing case statement in ralph_loop.sh (around line 3090-3220)
• Validate against allowed values: claude, copilot
• Set AGENT_PROVIDER environment variable (default: claude)
• Add to help text output with supported providers listed

Task 2: Create Agent Adapter Directory Structure

Establish the lib/agents/ directory and define the adapter interface contract through a documented pattern.

• Create lib/agents/ directory
• Create lib/agents/README.md documenting the adapter interface contract:
  • Required functions: build_<provider>_command(), get_<provider>_capabilities()
  • Global arrays used: AGENT_CMD_ARGS (new, provider-agnostic equivalent of CLAUDE_CMD_ARGS)
  • Capabilities struct format
• Create lib/agents/common.sh with shared utilities (capability logging, degraded-feature warnings)

Task 3: Add Provider Dispatch in Main Loop

Insert provider routing logic in execute_claude_code() that dispatches to the appropriate adapter's command builder.

• Source agent adapter files conditionally in ralph_loop.sh based on AGENT_PROVIDER
• In execute_claude_code() (around line 1830), add dispatch logic before build_claude_command():
  • If AGENT_PROVIDER == "claude": call existing build_claude_command()
  • If AGENT_PROVIDER == "copilot": call build_copilot_command() from sourced adapter
• Introduce AGENT_CMD_ARGS as the provider-agnostic command array, replacing CLAUDE_CMD_ARGS usage downstream
• Ensure sandbox wrapping (wrap_claude_command_for_sandbox()) works with either provider by operating on AGENT_CMD_ARGS

🤖 Prompt for AI agents

Implement the minimal provider dispatch infrastructure in `ralph_loop.sh` and
create the `lib/agents/` directory structure. The goal is to introduce
`--provider` flag routing while keeping all existing Claude behavior unchanged.

**1. Add `--provider` CLI flag in `ralph_loop.sh` (around line 3090-3220):**
- Add a `--provider` case to the argument parsing case statement
- Validate the value against allowed providers: `claude`, `copilot`; exit with
error on invalid value
- Set `AGENT_PROVIDER` variable (default: `claude`)
- Add `--provider` to the help text output, listing supported providers

**2. Create `lib/agents/` directory structure:**
- Create `lib/agents/README.md` documenting the adapter interface contract:
- Required functions: `build_<provider>_command()`,
`get_<provider>_capabilities()`
- Global arrays used: `AGENT_CMD_ARGS` (provider-agnostic equivalent of
`CLAUDE_CMD_ARGS`)
  - Capabilities struct format
- Create `lib/agents/common.sh` with shared utilities for capability logging and
degraded-feature warnings

**3. Add provider dispatch in `execute_claude_code()` (around line 1830):**
- Conditionally source the appropriate adapter file in `ralph_loop.sh` based on
`AGENT_PROVIDER`
- Before `build_claude_command()`, add dispatch logic:
  - If `AGENT_PROVIDER == "claude"`: call existing `build_claude_command()`
- If `AGENT_PROVIDER == "copilot"`: call `build_copilot_command()` from the
sourced adapter
- Introduce `AGENT_CMD_ARGS` as the provider-agnostic command array to replace
`CLAUDE_CMD_ARGS` usage downstream
- Ensure `wrap_claude_command_for_sandbox()` operates on `AGENT_CMD_ARGS` so
sandbox wrapping works for either provider

Phase 2: Copilot Adapter Implementation

Implement the Copilot-specific adapter with command building, capabilities declaration, and degraded-feature warning infrastructure.

Task 1: Implement Copilot Command Builder

Create lib/agents/copilot.sh with the build_copilot_command() function that assembles Copilot CLI arguments.

• Define COPILOT_CODE_CMD variable (default: copilot)
• Implement build_copilot_command(prompt_file, loop_context, session_id):
  • -p/--prompt with content from prompt file
  • -s/--silent for agent-response-only output
  • --resume <id> when session_id is provided (not --continue to match Claude's pattern)
  • --model from COPILOT_MODEL if set
  • --allow-tool/--deny-tool per-tool from COPILOT_ALLOWED_TOOLS/COPILOT_DENIED_TOOLS
  • --allow-all flag support via COPILOT_ALLOW_ALL_TOOLS
• Populate AGENT_CMD_ARGS array following the same pattern as build_claude_command()

Task 2: Implement Capabilities Declaration

Add get_copilot_capabilities() function that declares Copilot's degraded feature set and triggers appropriate warnings.

• Implement get_copilot_capabilities() returning structured capabilities:
  • structured_output=false (text-only)
  • token_usage=false
  • permission_denials=false (note: rich permissions at build time via --allow-tool/--deny-tool)
  • api_limit_detection=false
  • session_type=resume-id
• Call capability check on provider initialization
• Use shared function from lib/agents/common.sh to log warnings for each disabled feature:
  • "Token usage tracking disabled (Copilot does not provide structured output)"
  • "Permission denial circuit breaker disabled (Copilot text output cannot detect denials)"
  • "API limit detection disabled (Copilot does not expose rate limit events)"

Task 3: Force Text-Mode Parsing Path

Ensure Copilot responses flow through the existing text-mode parsing infrastructure in response_analyzer.sh.

• When AGENT_PROVIDER == "copilot", force AGENT_OUTPUT_FORMAT=text regardless of configuration
• Ensure detect_output_format() returns "text" for Copilot output
• Verify RALPH_STATUS block detection works for Copilot output (the existing regex ^[[:space:]]*(---RALPH_STATUS---|RALPH_STATUS:) should work)
• Confirm Issue #224 text-mode threshold (confidence_score >= 70 AND has_completion_signal) applies
• Update analyze_response() to skip JSON-only extraction paths when provider is Copilot

Task 4: Wire Configuration Defaults

Add Copilot configuration variables to .ralphrc template and establish defaults.

• Add to templates/ralphrc.template:
  • COPILOT_CODE_CMD (commented, default: copilot)
  • COPILOT_MODEL (commented, no default)
  • COPILOT_ALLOWED_TOOLS / COPILOT_DENIED_TOOLS (commented)
  • COPILOT_ALLOW_ALL_TOOLS (commented, default: false)
• Update lib/enable_core.sh generate_ralphrc() to include Copilot section (commented out by default)
• Add Copilot variables to environment variable snapshot at start of ralph_loop.sh (pattern matches line 71)

🤖 Prompt for AI agents

Create `lib/agents/copilot.sh` implementing the full Copilot provider adapter,
and update related files for text-mode parsing and configuration. The goal is a
working Copilot adapter that builds CLI commands, declares capabilities with
degraded-feature warnings, forces text-mode parsing, and exposes configuration
defaults.

**1. Create `lib/agents/copilot.sh`:**
- Define `COPILOT_CODE_CMD` variable with default value `copilot`
- Implement `build_copilot_command(prompt_file, loop_context, session_id)` that
populates `AGENT_CMD_ARGS` array:
  - Add `-p`/`--prompt` with content from prompt file
  - Add `-s`/`--silent` for agent-response-only output
  - Add `--resume <id>` when session_id is provided (not `--continue`)
  - Conditionally add `--model` from `COPILOT_MODEL` if set
  - Iterate `COPILOT_ALLOWED_TOOLS` adding `--allow-tool` per entry
  - Iterate `COPILOT_DENIED_TOOLS` adding `--deny-tool` per entry
  - Add `--allow-all` flag when `COPILOT_ALLOW_ALL_TOOLS=true`
  - Follow the same array-population pattern used in `build_claude_command()`
- Implement `get_copilot_capabilities()` returning structured capabilities:
- `structured_output=false`, `token_usage=false`, `permission_denials=false`,
`api_limit_detection=false`, `session_type=resume-id`
  - Call this function on provider initialization
- Use the shared function from `lib/agents/common.sh` to log a warning for each
disabled feature with these exact messages:
- "Token usage tracking disabled (Copilot does not provide structured output)"
- "Permission denial circuit breaker disabled (Copilot text output cannot detect
denials)"
    - "API limit detection disabled (Copilot does not expose rate limit events)"

**2. Force text-mode parsing in `response_analyzer.sh`:**
- When `AGENT_PROVIDER == "copilot"`, set `AGENT_OUTPUT_FORMAT=text`
unconditionally (ignoring any user configuration)
- Update `detect_output_format()` to return `"text"` for Copilot output
- Update `analyze_response()` to skip JSON-only extraction paths when the
provider is Copilot
- Confirm the existing RALPH_STATUS block regex
`^[[:space:]]*(---RALPH_STATUS---|RALPH_STATUS:)` and Issue `#224` threshold
(`confidence_score >= 70 AND has_completion_signal`) apply without modification

**3. Add configuration defaults:**
- In `templates/ralphrc.template`, add a commented Copilot section with:
`COPILOT_CODE_CMD` (default: `copilot`), `COPILOT_MODEL` (no default),
`COPILOT_ALLOWED_TOOLS`, `COPILOT_DENIED_TOOLS`, `COPILOT_ALLOW_ALL_TOOLS`
(default: `false`)
- Update `generate_ralphrc()` in `lib/enable_core.sh` to include the Copilot
section (commented out by default)
- Add Copilot variables to the environment variable snapshot near line 71 of
`ralph_loop.sh`

Phase 3: Testing and Documentation

Add comprehensive tests and documentation for the Copilot adapter and provider routing system.

Task 1: Unit Tests for Copilot Adapter

Create tests/unit/test_copilot_adapter.bats with unit tests for command building and capabilities.

• Follow existing test patterns from test_sandbox_docker.bats and test_sandbox_e2b.bats
• Test build_copilot_command():
  • Basic invocation produces expected argv structure
  • Session resume adds --resume <id>
  • Model override adds --model
  • Tool allow/deny flags correctly passed
  • --allow-all flag when COPILOT_ALLOW_ALL_TOOLS=true
• Test get_copilot_capabilities():
  • Returns correct capability values
  • Warnings are logged for each degraded feature
• Use mock recording pattern (write args to $TEST_DIR/copilot_args)

Task 2: Integration Tests for Provider Routing

Create tests/integration/test_provider_routing.bats with tests for the dispatch mechanism.

• Test --provider claude uses build_claude_command() (default behavior preserved)
• Test --provider copilot sources lib/agents/copilot.sh and uses build_copilot_command()
• Test invalid --provider foo fails with appropriate error
• Test Copilot forces text output format regardless of --output-format json
• Test capability warnings are logged when using Copilot provider

Task 3: Create Copilot Provider Documentation

Create docs/providers/COPILOT.md documenting the Copilot adapter's reduced feature set and usage.

• Create docs/providers/ directory
• Document Copilot adapter usage: ralph --provider copilot
• List supported CLI flags and their Copilot CLI equivalents
• Document configuration variables (COPILOT_CODE_CMD, COPILOT_MODEL, etc.)
• Explicitly call out reduced feature set:
  • No token usage tracking
  • No permission denial detection (circuit breaker trigger disabled)
  • No API limit detection
  • Exit detection relies on RALPH_STATUS block or text heuristics
• Include troubleshooting section for common Copilot-specific issues

Task 4: Update README Provider Documentation

Add Copilot to the README's provider documentation.

• Add Copilot to the Features section (around line 157-158) in the same bullet pattern as Docker/E2B sandbox
• Consider creating a "Supported Providers" table if it improves clarity:
  • Provider | Structured Output | Token Tracking | Exit Detection
  • Claude | Yes (JSON) | Yes | RALPH_STATUS + JSON fields
  • Copilot | No (text) | No | RALPH_STATUS + text heuristics
• Link to docs/providers/COPILOT.md for full details
• Update any "Claude-only" language to reflect multi-provider support

🤖 Prompt for AI agents

Create unit tests, integration tests, and documentation for the Copilot adapter
and provider routing system. The goal is comprehensive test coverage and clear
documentation consistent with existing codebase patterns.

**1. Create `tests/unit/test_copilot_adapter.bats`:**
- Follow test patterns from `test_sandbox_docker.bats` and
`test_sandbox_e2b.bats`
- Use mock recording pattern: write args to `$TEST_DIR/copilot_args`
- Test `build_copilot_command()`:
  - Basic invocation produces expected argv structure
  - Session resume adds `--resume <id>`
  - Model override adds `--model`
  - Tool allow/deny flags are correctly passed
  - `--allow-all` flag is present when `COPILOT_ALLOW_ALL_TOOLS=true`
- Test `get_copilot_capabilities()`:
  - Returns correct capability values
  - Warnings are logged for each degraded feature

**2. Create `tests/integration/test_provider_routing.bats`:**
- Test that `--provider claude` uses `build_claude_command()` (default behavior
preserved)
- Test that `--provider copilot` sources `lib/agents/copilot.sh` and uses
`build_copilot_command()`
- Test that an invalid `--provider foo` fails with an appropriate error
- Test that Copilot forces text output format regardless of `--output-format
json`
- Test that capability warnings are logged when using Copilot provider

**3. Create `docs/providers/COPILOT.md`:**
- Create the `docs/providers/` directory
- Document usage: `ralph --provider copilot`
- List supported CLI flags and their Copilot CLI equivalents
- Document all configuration variables: `COPILOT_CODE_CMD`, `COPILOT_MODEL`,
`COPILOT_ALLOWED_TOOLS`, `COPILOT_DENIED_TOOLS`, `COPILOT_ALLOW_ALL_TOOLS`
- Explicitly document the reduced feature set: no token usage tracking, no
permission denial detection (circuit breaker trigger disabled), no API limit
detection, exit detection relies on RALPH_STATUS block or text heuristics
- Include a troubleshooting section for common Copilot-specific issues

**4. Update `README.md`:**
- Add Copilot to the Features section (around line 157-158) using the same
bullet pattern as Docker/E2B sandbox entries
- Optionally add a "Supported Providers" table with columns: Provider |
Structured Output | Token Tracking | Exit Detection
- Link to `docs/providers/COPILOT.md` for full details
- Update any "Claude-only" language to reflect multi-provider support

Research

Ralph is a bash-based autonomous loop orchestrator tightly coupled to the Claude Code CLI. The main execution flow lives in ralph_loop.sh, with build_claude_command() (lines 1535-1627) assembling CLI arguments and execute_claude_code() (lines 1776-2433) orchestrating build, execution, and analysis. Response parsing in lib/response_analyzer.sh already handles both JSON and text modes, with text-mode using RALPH_STATUS block detection and heuristic scoring (Issue #224 defenses). The codebase has no lib/agents/ directory, no --provider flag, and no adapter abstraction. Tests use bats framework in tests/unit/ and tests/integration/ with mock-recording patterns. Documentation lives in docs/ but no docs/providers/ directory exists.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the minimal provider dispatch infrastructure in `ralph_loop.sh` and
create the `lib/agents/` directory structure. The goal is to introduce
`--provider` flag routing while keeping all existing Claude behavior unchanged.

**1. Add `--provider` CLI flag in `ralph_loop.sh` (around line 3090-3220):**
- Add a `--provider` case to the argument parsing case statement
- Validate the value against allowed providers: `claude`, `copilot`; exit with
error on invalid value
- Set `AGENT_PROVIDER` variable (default: `claude`)
- Add `--provider` to the help text output, listing supported providers

**2. Create `lib/agents/` directory structure:**
- Create `lib/agents/README.md` documenting the adapter interface contract:
- Required functions: `build_<provider>_command()`,
`get_<provider>_capabilities()`
- Global arrays used: `AGENT_CMD_ARGS` (provider-agnostic equivalent of
`CLAUDE_CMD_ARGS`)
  - Capabilities struct format
- Create `lib/agents/common.sh` with shared utilities for capability logging and
degraded-feature warnings

**3. Add provider dispatch in `execute_claude_code()` (around line 1830):**
- Conditionally source the appropriate adapter file in `ralph_loop.sh` based on
`AGENT_PROVIDER`
- Before `build_claude_command()`, add dispatch logic:
  - If `AGENT_PROVIDER == "claude"`: call existing `build_claude_command()`
- If `AGENT_PROVIDER == "copilot"`: call `build_copilot_command()` from the
sourced adapter
- Introduce `AGENT_CMD_ARGS` as the provider-agnostic command array to replace
`CLAUDE_CMD_ARGS` usage downstream
- Ensure `wrap_claude_command_for_sandbox()` operates on `AGENT_CMD_ARGS` so
sandbox wrapping works for either provider
===============================================================================

Task: 2

Create `lib/agents/copilot.sh` implementing the full Copilot provider adapter,
and update related files for text-mode parsing and configuration. The goal is a
working Copilot adapter that builds CLI commands, declares capabilities with
degraded-feature warnings, forces text-mode parsing, and exposes configuration
defaults.

**1. Create `lib/agents/copilot.sh`:**
- Define `COPILOT_CODE_CMD` variable with default value `copilot`
- Implement `build_copilot_command(prompt_file, loop_context, session_id)` that
populates `AGENT_CMD_ARGS` array:
  - Add `-p`/`--prompt` with content from prompt file
  - Add `-s`/`--silent` for agent-response-only output
  - Add `--resume <id>` when session_id is provided (not `--continue`)
  - Conditionally add `--model` from `COPILOT_MODEL` if set
  - Iterate `COPILOT_ALLOWED_TOOLS` adding `--allow-tool` per entry
  - Iterate `COPILOT_DENIED_TOOLS` adding `--deny-tool` per entry
  - Add `--allow-all` flag when `COPILOT_ALLOW_ALL_TOOLS=true`
  - Follow the same array-population pattern used in `build_claude_command()`
- Implement `get_copilot_capabilities()` returning structured capabilities:
- `structured_output=false`, `token_usage=false`, `permission_denials=false`,
`api_limit_detection=false`, `session_type=resume-id`
  - Call this function on provider initialization
- Use the shared function from `lib/agents/common.sh` to log a warning for each
disabled feature with these exact messages:
- "Token usage tracking disabled (Copilot does not provide structured output)"
- "Permission denial circuit breaker disabled (Copilot text output cannot detect
denials)"
    - "API limit detection disabled (Copilot does not expose rate limit events)"

**2. Force text-mode parsing in `response_analyzer.sh`:**
- When `AGENT_PROVIDER == "copilot"`, set `AGENT_OUTPUT_FORMAT=text`
unconditionally (ignoring any user configuration)
- Update `detect_output_format()` to return `"text"` for Copilot output
- Update `analyze_response()` to skip JSON-only extraction paths when the
provider is Copilot
- Confirm the existing RALPH_STATUS block regex
`^[[:space:]]*(---RALPH_STATUS---|RALPH_STATUS:)` and Issue `#224` threshold
(`confidence_score >= 70 AND has_completion_signal`) apply without modification

**3. Add configuration defaults:**
- In `templates/ralphrc.template`, add a commented Copilot section with:
`COPILOT_CODE_CMD` (default: `copilot`), `COPILOT_MODEL` (no default),
`COPILOT_ALLOWED_TOOLS`, `COPILOT_DENIED_TOOLS`, `COPILOT_ALLOW_ALL_TOOLS`
(default: `false`)
- Update `generate_ralphrc()` in `lib/enable_core.sh` to include the Copilot
section (commented out by default)
- Add Copilot variables to the environment variable snapshot near line 71 of
`ralph_loop.sh`
===============================================================================

Task: 3

Create unit tests, integration tests, and documentation for the Copilot adapter
and provider routing system. The goal is comprehensive test coverage and clear
documentation consistent with existing codebase patterns.

**1. Create `tests/unit/test_copilot_adapter.bats`:**
- Follow test patterns from `test_sandbox_docker.bats` and
`test_sandbox_e2b.bats`
- Use mock recording pattern: write args to `$TEST_DIR/copilot_args`
- Test `build_copilot_command()`:
  - Basic invocation produces expected argv structure
  - Session resume adds `--resume <id>`
  - Model override adds `--model`
  - Tool allow/deny flags are correctly passed
  - `--allow-all` flag is present when `COPILOT_ALLOW_ALL_TOOLS=true`
- Test `get_copilot_capabilities()`:
  - Returns correct capability values
  - Warnings are logged for each degraded feature

**2. Create `tests/integration/test_provider_routing.bats`:**
- Test that `--provider claude` uses `build_claude_command()` (default behavior
preserved)
- Test that `--provider copilot` sources `lib/agents/copilot.sh` and uses
`build_copilot_command()`
- Test that an invalid `--provider foo` fails with an appropriate error
- Test that Copilot forces text output format regardless of `--output-format
json`
- Test that capability warnings are logged when using Copilot provider

**3. Create `docs/providers/COPILOT.md`:**
- Create the `docs/providers/` directory
- Document usage: `ralph --provider copilot`
- List supported CLI flags and their Copilot CLI equivalents
- Document all configuration variables: `COPILOT_CODE_CMD`, `COPILOT_MODEL`,
`COPILOT_ALLOWED_TOOLS`, `COPILOT_DENIED_TOOLS`, `COPILOT_ALLOW_ALL_TOOLS`
- Explicitly document the reduced feature set: no token usage tracking, no
permission denial detection (circuit breaker trigger disabled), no API limit
detection, exit detection relies on RALPH_STATUS block or text heuristics
- Include a troubleshooting section for common Copilot-specific issues

**4. Update `README.md`:**
- Add Copilot to the Features section (around line 157-158) using the same
bullet pattern as Docker/E2B sandbox entries
- Optionally add a "Supported Providers" table with columns: Provider |
Structured Output | Token Tracking | Exit Detection
- Link to `docs/providers/COPILOT.md` for full details
- Update any "Claude-only" language to reflect multi-provider support

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!