[P1.1] Command-construction seam: lib/agents/ registry + Claude reference adapter

[frankbria]

Phase 1 — Abstraction seam. Extract command building behind the adapter contract
with Claude as the reference implementation. Zero behavior change.

Scope

• New lib/agents/ with a registry and lib/agents/claude.sh implementing the
  command-build half of the [P0.2] contract.
• Refactor build_claude_command() in ralph_loop.sh to delegate to the active
  adapter. Claude adapter must reproduce today's exact argv:
  --model/--effort, --output-format json, --allowedTools …, --resume <id>,
  --append-system-prompt <ctx>, -p <prompt>, plus the RALPH_VERBOSE argv dump.
• Keep the _env_* capture-before-source ordering convention (lib sets defaults at
  source time — see sandbox libs).

Acceptance

• Full suite green; argv byte-identical for the Claude path (add a golden-args test).
• No new provider yet; selection still hardcoded to claude.

Depends on: [P0.2]. Blocks: [P1.2], [P1.3], [P3.1].

[coderabbitai]

🔗 Related PRs

#231 - fix(loop): respect .ralphrc CLAUDE_CODE_CMD; add CLAUDE_MODEL/EFFORT (#228) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

🏷️ Triage: Enhancement

Thanks for the detailed write-up! Here's how this issue was categorized:

Category: Feature / Enhancement → applied the enhancement label.

Reasoning:

• This is planned refactoring work (introducing the lib/agents/ adapter seam with Claude as the reference implementation), not a defect — so it's not a bug.
• It's well-specified: clear scope, explicit acceptance criteria (full suite green, byte-identical Claude argv via a golden-args test), and a dependency graph. No additional information is needed, so no needs-info.
• Not a duplicate. This is a distinct node in the multi-provider roadmap. In particular it does not overlap with its sibling [P1.2] Output-normalization seam: internal analysis struct + Claude parser #313 ([P1.2]), which covers the output-normalization seam — [P1.1] Command-construction seam: lib/agents/ registry + Claude reference adapter #312 is strictly the command-construction half.

Dependency context (from the issue):

• Depends on: [P0.2] Define adapter interface contract + capabilities schema #311 ([P0.2] adapter interface contract) — that design should land first so this implementation targets a ratified contract.
• Blocks: [P1.2] Output-normalization seam: internal analysis struct + Claude parser #313 ([P1.2]), [P1.3] Provider selection surface: AGENT_PROVIDER config + CLI + tmux forwarding #314 ([P1.3]), [P3.1] Codex adapter (pilot) — build + parse + capabilities + tests + docs #317 ([P3.1]).

Recommended next steps:

1. Confirm [P0.2] Define adapter interface contract + capabilities schema #311 ([P0.2]) is merged (or stable) before starting, since the adapter contract defines the command-build fields this issue implements.
2. When implementing, preserve the _env_* capture-before-source ordering convention (per the sandbox libs) and keep the RALPH_VERBOSE argv dump intact.
3. Add the golden-args test asserting byte-identical Claude argv so the "zero behavior change" guarantee is enforced in CI.

No assignee was set — assignment is reserved for confirmed bugs.

Generated by Issue Triage Assistant for issue #312 · opus48 608.9K · ◷

[coderabbitai]

Coding Plan

Summary

• Create a minimal registry pattern in lib/agents/ following existing sandbox adapter conventions—dispatch via case statement, all adapters sourced unconditionally
• Claude adapter extracts the current build_claude_command() logic verbatim, ensuring byte-identical argv output
• The refactor in ralph_loop.sh is a pure delegation—the function signature and output interface (CLAUDE_CMD_ARGS) remain unchanged
• Golden-args test provides regression safety and documents the expected argv contract

Implementation Steps

Phase 1: Agent Registry Infrastructure

Establish the lib/agents/ directory structure with a registry that defines the adapter contract and provides the dispatch mechanism. This phase creates the foundational abstraction without changing any runtime behavior.

Create Agent Registry Module

Establish the registry that defines the command-build contract and handles adapter dispatch.

• Create lib/agents/registry.sh with a module-level comment documenting the adapter contract: adapters must implement a function that receives (prompt_file, loop_context, session_id) and populates the global CLAUDE_CMD_ARGS array
• Define AGENT_PROVIDER="${AGENT_PROVIDER:-claude}" at source time (hardcoded default for now)
• Implement agent_build_command() dispatch function that routes to the active provider's build function via a case statement on AGENT_PROVIDER
• Include the standard logging abstraction fallback pattern (declare -F log_status check)
• End with export -f agent_build_command for subshell availability

🤖 Prompt for AI agents

Create the `lib/agents/registry.sh` file, establishing the foundational agent
registry module. This phase introduces the adapter contract and dispatch
mechanism with no runtime behavior changes.

- Create the `lib/agents/` directory and `lib/agents/registry.sh`
- Add a module-level comment documenting the adapter contract: adapters must
implement a function receiving `(prompt_file, loop_context, session_id)` and
populating the global `CLAUDE_CMD_ARGS` array
- At source time, define `AGENT_PROVIDER="${AGENT_PROVIDER:-claude}"` (hardcoded
default)
- Implement `agent_build_command()` that dispatches to the active provider's
build function using a `case` statement on `$AGENT_PROVIDER`
- Include the standard logging abstraction fallback pattern using a `declare -F
log_status` check
- End with `export -f agent_build_command` for subshell availability
- Follow existing lib/ conventions: shebang, module-level defaults at source
time, `_`-prefixed private helpers if needed

Phase 2: Claude Reference Adapter

Implement the Claude adapter that reproduces the exact behavior of today's build_claude_command(), including all flag construction and the RALPH_VERBOSE argv dump.

Implement Claude Command Builder

Create the Claude-specific adapter that implements the command-build contract.

• Create lib/agents/claude.sh following lib/ conventions (shebang, module comment referencing this ticket)
• Implement claude_build_command() that takes (prompt_file, loop_context, session_id) parameters
• Reproduce the exact flag construction order from current build_claude_command():
  • Start with CLAUDE_CODE_CMD as argv[0]
  • Add --model only when CLAUDE_MODEL is non-empty
  • Add --effort only when CLAUDE_EFFORT is non-empty
  • Add --output-format json when CLAUDE_OUTPUT_FORMAT == "json"
  • Add --allowedTools with each comma-separated tool as a separate array element
  • Add --resume <session_id> when CLAUDE_USE_CONTINUE=true and session_id is non-empty
  • Add --append-system-prompt <loop_context> when loop_context is non-empty
  • Add -p <prompt_content> (read prompt file content)
• Move the RALPH_VERBOSE argv dump logic into this adapter (redact prompt body as <prompt:N chars>)
• End with export -f claude_build_command

🤖 Prompt for AI agents

Create `lib/agents/claude.sh`, the Claude-specific adapter implementing the
command-build contract. The goal is a byte-identical reproduction of the current
`build_claude_command()` flag construction logic.

- Create `lib/agents/claude.sh` with a shebang and module comment referencing
this ticket, following existing lib/ conventions
- Implement `claude_build_command()` accepting parameters `(prompt_file,
loop_context, session_id)` and populating the global `CLAUDE_CMD_ARGS` array
- Reproduce flag construction in this exact order:
  - `CLAUDE_CODE_CMD` as argv[0]
  - `--model` only when `CLAUDE_MODEL` is non-empty
  - `--effort` only when `CLAUDE_EFFORT` is non-empty
  - `--output-format json` when `CLAUDE_OUTPUT_FORMAT == "json"`
  - `--allowedTools` with each comma-separated tool as a separate array element
- `--resume <session_id>` when `CLAUDE_USE_CONTINUE=true` and session_id is
non-empty
  - `--append-system-prompt <loop_context>` when loop_context is non-empty
  - `-p <prompt_content>` (read prompt file content)
- Move the RALPH_VERBOSE argv dump logic from `build_claude_command()` into this
adapter, redacting the prompt body as `<prompt:N chars>`
- End with `export -f claude_build_command`

Phase 3: Integration and Validation

Wire the new agent registry into ralph_loop.sh, maintaining the existing _env_* capture ordering, and add a golden-args test to verify byte-identical output.

Task 1: Source Agent Libraries in ralph_loop.sh

Integrate the new agent libs into the sourcing chain with correct ordering.

• Add source statements for lib/agents/registry.sh and lib/agents/claude.sh at the end of the existing source block (lines 37-47)
• No new _env_* captures needed—the Claude adapter uses existing CLAUDE_* variables which are already captured in Wave 2
• AGENT_PROVIDER is hardcoded to claude and not user-configurable yet, so no capture needed

Task 2: Refactor build_claude_command() to Delegate

Replace the inline implementation with a thin wrapper that delegates to the registry.

• Modify build_claude_command() (currently lines 1535-1627) to become a delegation wrapper
• The wrapper should call agent_build_command "$@" and return its result
• Keep the function signature identical: build_claude_command prompt_file loop_context session_id
• Preserve the global CLAUDE_CMD_ARGS array as the output interface (populated by the adapter)
• Remove the inline flag construction logic (now lives in claude_build_command())
• All downstream consumers (wrap_claude_command_for_sandbox(), LIVE_CMD_ARGS construction, execution paths) continue using CLAUDE_CMD_ARGS unchanged

Task 3: Add Golden-Args Unit Test

Create a test that verifies the Claude adapter produces byte-identical argv.

• Create tests/unit/test_agent_claude.bats following existing test patterns
• Source lib/agents/registry.sh and lib/agents/claude.sh directly (Pattern A from exploration)
• Test cases should cover all flag combinations:
  • Basic invocation with just prompt
  • With CLAUDE_MODEL set
  • With CLAUDE_EFFORT set
  • With CLAUDE_ALLOWED_TOOLS containing multiple tools
  • With CLAUDE_USE_CONTINUE=true and session_id
  • With loop_context for append-system-prompt
  • With RALPH_VERBOSE=true (verify dump happens without breaking)
• Assert exact array contents using positional access pattern from test_cli_modern.bats
• Verify no --dangerously-skip-permissions flag is ever present (security invariant)

Task 4: Verify Existing Test Suite Passes

Ensure the refactor maintains backward compatibility.

• Run full test suite to verify all existing test_cli_modern.bats tests pass unchanged
• Verify E2E tests that check argv still pass (they test the final invocation path)
• No test modifications should be needed if the abstraction is behavior-preserving

🤖 Prompt for AI agents

Wire the new agent registry into `ralph_loop.sh` and add a golden-args test.
This phase integrates the new libs, refactors `build_claude_command()` to a thin
delegation wrapper, and validates byte-identical behavior.

**Source Agent Libraries in `ralph_loop.sh`:**
- Add source statements for `lib/agents/registry.sh` and `lib/agents/claude.sh`
at the end of the existing source block (lines 37-47)
- No new `_env_*` captures are needed; Claude adapter uses existing `CLAUDE_*`
variables already captured in Wave 2
- `AGENT_PROVIDER` is hardcoded and not user-configurable yet, so no capture is
needed

**Refactor `build_claude_command()` (lines 1535-1627):**
- Replace the inline flag construction logic with a delegation wrapper that
calls `agent_build_command "$@"` and returns its result
- Keep the function signature identical: `build_claude_command prompt_file
loop_context session_id`
- Preserve the global `CLAUDE_CMD_ARGS` array as the output interface
- All downstream consumers (`wrap_claude_command_for_sandbox()`, `LIVE_CMD_ARGS`
construction, execution paths) remain unchanged

**Add Golden-Args Unit Test (`tests/unit/test_agent_claude.bats`):**
- Follow existing test patterns; source `lib/agents/registry.sh` and
`lib/agents/claude.sh` directly
- Cover all flag combination test cases:
  - Basic invocation with just prompt
  - With `CLAUDE_MODEL` set
  - With `CLAUDE_EFFORT` set
  - With `CLAUDE_ALLOWED_TOOLS` containing multiple tools
  - With `CLAUDE_USE_CONTINUE=true` and session_id
  - With `loop_context` for append-system-prompt
  - With `RALPH_VERBOSE=true` (verify dump happens without breaking)
- Assert exact array contents using the positional access pattern from
`test_cli_modern.bats`
- Verify no `--dangerously-skip-permissions` flag is ever present (security
invariant)

**Verify Existing Tests:**
- Run full test suite to confirm all existing `test_cli_modern.bats` tests pass
unchanged
- Verify E2E tests that check argv still pass
- No test modifications should be needed if the abstraction is
behavior-preserving

Research

The codebase uses a consistent lib/ pattern: each file sets module-level defaults at source time using ${VAR:-default}, defines private _-prefixed helpers alongside public API functions, uses a logging abstraction that falls back gracefully, and ends with export -f for all public functions. The existing adapter pattern (seen in sandbox providers) uses a string enum as a registry key with case-based dispatch—all provider libs are sourced unconditionally and selection happens at call time. The _env_* two-wave capture convention preserves environment variable priority over .ralphrc values. Command construction currently happens in build_claude_command() which populates the global CLAUDE_CMD_ARGS array, later consumed by sandbox wrapping and execution paths.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create the `lib/agents/registry.sh` file, establishing the foundational agent
registry module. This phase introduces the adapter contract and dispatch
mechanism with no runtime behavior changes.

- Create the `lib/agents/` directory and `lib/agents/registry.sh`
- Add a module-level comment documenting the adapter contract: adapters must
implement a function receiving `(prompt_file, loop_context, session_id)` and
populating the global `CLAUDE_CMD_ARGS` array
- At source time, define `AGENT_PROVIDER="${AGENT_PROVIDER:-claude}"` (hardcoded
default)
- Implement `agent_build_command()` that dispatches to the active provider's
build function using a `case` statement on `$AGENT_PROVIDER`
- Include the standard logging abstraction fallback pattern using a `declare -F
log_status` check
- End with `export -f agent_build_command` for subshell availability
- Follow existing lib/ conventions: shebang, module-level defaults at source
time, `_`-prefixed private helpers if needed
===============================================================================

Task: 2

Create `lib/agents/claude.sh`, the Claude-specific adapter implementing the
command-build contract. The goal is a byte-identical reproduction of the current
`build_claude_command()` flag construction logic.

- Create `lib/agents/claude.sh` with a shebang and module comment referencing
this ticket, following existing lib/ conventions
- Implement `claude_build_command()` accepting parameters `(prompt_file,
loop_context, session_id)` and populating the global `CLAUDE_CMD_ARGS` array
- Reproduce flag construction in this exact order:
  - `CLAUDE_CODE_CMD` as argv[0]
  - `--model` only when `CLAUDE_MODEL` is non-empty
  - `--effort` only when `CLAUDE_EFFORT` is non-empty
  - `--output-format json` when `CLAUDE_OUTPUT_FORMAT == "json"`
  - `--allowedTools` with each comma-separated tool as a separate array element
- `--resume <session_id>` when `CLAUDE_USE_CONTINUE=true` and session_id is
non-empty
  - `--append-system-prompt <loop_context>` when loop_context is non-empty
  - `-p <prompt_content>` (read prompt file content)
- Move the RALPH_VERBOSE argv dump logic from `build_claude_command()` into this
adapter, redacting the prompt body as `<prompt:N chars>`
- End with `export -f claude_build_command`
===============================================================================

Task: 3

Wire the new agent registry into `ralph_loop.sh` and add a golden-args test.
This phase integrates the new libs, refactors `build_claude_command()` to a thin
delegation wrapper, and validates byte-identical behavior.

**Source Agent Libraries in `ralph_loop.sh`:**
- Add source statements for `lib/agents/registry.sh` and `lib/agents/claude.sh`
at the end of the existing source block (lines 37-47)
- No new `_env_*` captures are needed; Claude adapter uses existing `CLAUDE_*`
variables already captured in Wave 2
- `AGENT_PROVIDER` is hardcoded and not user-configurable yet, so no capture is
needed

**Refactor `build_claude_command()` (lines 1535-1627):**
- Replace the inline flag construction logic with a delegation wrapper that
calls `agent_build_command "$@"` and returns its result
- Keep the function signature identical: `build_claude_command prompt_file
loop_context session_id`
- Preserve the global `CLAUDE_CMD_ARGS` array as the output interface
- All downstream consumers (`wrap_claude_command_for_sandbox()`, `LIVE_CMD_ARGS`
construction, execution paths) remain unchanged

**Add Golden-Args Unit Test (`tests/unit/test_agent_claude.bats`):**
- Follow existing test patterns; source `lib/agents/registry.sh` and
`lib/agents/claude.sh` directly
- Cover all flag combination test cases:
  - Basic invocation with just prompt
  - With `CLAUDE_MODEL` set
  - With `CLAUDE_EFFORT` set
  - With `CLAUDE_ALLOWED_TOOLS` containing multiple tools
  - With `CLAUDE_USE_CONTINUE=true` and session_id
  - With `loop_context` for append-system-prompt
  - With `RALPH_VERBOSE=true` (verify dump happens without breaking)
- Assert exact array contents using the positional access pattern from
`test_cli_modern.bats`
- Verify no `--dangerously-skip-permissions` flag is ever present (security
invariant)

**Verify Existing Tests:**
- Run full test suite to confirm all existing `test_cli_modern.bats` tests pass
unchanged
- Verify E2E tests that check argv still pass
- No test modifications should be needed if the abstraction is
behavior-preserving

💡 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!