feat: bounded provider-neutral CLI agents and review contracts

[EmersonBraun]

Bounded provider-neutral CLI agents and review contracts

Context

AgentsKit Code Review must support multiple API providers and local coding CLIs without breaking the existing AdapterFactory contract or producing reviews that appear complete when execution was partial.

The next local CLI integrations are:

• grok-cli: official Grok Build CLI;
• opencode-cli: OpenCode CLI.

The approved architecture is documented in ADR-0001 and proposed in PR #36.

flowchart LR
  Input["Diff / PR / paths / stdin"] --> Normalize["Normalize code + infra/config"]
  Normalize --> Policy["Trusted policy + lenses + budgets"]
  Policy --> Worker["One provider worker per lens"]
  Worker --> Transport{"ACP or headless"}
  Transport --> Envelope["Versioned JSON envelope"]
  Envelope --> Validate["Schema + coverage + retry"]
  Validate --> Verify["Adversarial verification"]
  Verify --> Report["Markdown / GitHub / SARIF"]

Loading

Goal

Implement the approved architecture in small, independently verifiable slices while preserving existing provider IDs, flags, exit codes, AdapterFactory behavior, advisory semantics, and current Codex/Claude/Ollama integrations.

Non-negotiable contracts

• grok remains the xAI API provider; grok-cli is the local Grok Build CLI.
• opencode-cli is the local OpenCode CLI.
• ACP is the default CLI transport; headless is explicit; auto is local-only.
• isolated is the CI default; trusted-local is explicit and local-only.
• CLI agents are workers for one lens; the review engine remains the orchestrator.
• Strict versioned JSON output is required; malformed output fails the lens.
• Required-lens failures produce INCOMPLETE and exit 2.
• maxCalls always has an absolute ceiling; unlimited mode does not exist.
• Fork PRs without credentials are SKIPPED/INCOMPLETE, never approvals.
• Project configuration and instructions cannot relax CI security policy.
• No executable plugins are loaded from the repository under review.

Acceptance criteria for the parent

• ADR-0001 is merged and linked from the implementation issues.
• Stable provider registry exists for API and CLI providers.
• Grok Build and OpenCode pass offline ACP/headless contract fixtures.
• Isolated execution sanitizes environment, filesystem/context, tools, and diagnostics.
• Review configuration is versioned and has trusted/untrusted precedence rules.
• Lens coverage, incomplete status, retries, budgets, and exit codes are tested.
• GitHub reporting is timeout-bounded and idempotent across pushes.
• Existing npm run check remains green and all new stable paths have offline tests.

Execution order

1. Foundations: #38 provider registry and doctor, #39 review configuration and lens policy.
2. Safety boundary: #40 bounded local CLI worker.
3. Providers: #41 Grok ACP, #42 OpenCode ACP.
4. Transport/context: #43 explicit headless transport, #44 bounded context and redaction.
5. Review correctness: #45 coverage, budgets, and preflight.
6. Delivery: #46 incremental and fork-safe GitHub reporting, #47 provider compatibility matrix, #48 documentation and operations.

Dependencies are recorded on each child issue. Parallel work is safe only where the listed dependencies are satisfied.

Deliberately out of scope

• automatic installation of third-party CLIs in the Action;
• privileged pull_request_target execution;
• unlimited review mode;
• executable plugins from project files;
• external state database for incremental reviews;
• autonomous CLI-agent orchestration of the review pipeline.

Implementation issues

Every child issue must reference this parent and satisfy its own acceptance criteria before the parent can close.