feat(kiro): make Kiro CLI v3 the default provider engine

# Make Kiro CLI v3 the Default Provider Engine

**Type:** enhancement
**Status:** draft
**Date:** 2026-08-17

## Problem / Opportunity

CAO defaults Kiro sessions to the v2 engine. PR #470 (`6b1978f`) intentionally
introduced only a Phase 0 boundary: `engine: v2|kas`, v2 as the default, a
capability probe, and a fail-closed rejection of the non-v2 path before
terminal allocation. That is a good safety boundary, but it does not deliver
Kiro CLI v3 as the normal CAO experience.

This leaves Kiro's current agent model, session behavior, and upcoming plugin
surface outside the default path. It also risks a partial migration where a
session can start in v3 but CAO's handoff/assign delivery, completion
detection, agent files, steering, hooks, or MCP integrations still assume the
v2 TUI and profile contract.

## Research Findings

Verified locally with Kiro CLI `2.17.0`:

- `kiro-cli chat --agent-engine v3` is accepted; chat help lists
`v1`, `v2` (default), and `v3`.
- `kiro-cli --v3 chat` is also accepted. `--mode default|spec` and
`--cloud` are v3-specific options.
- The CLI has first-class agent operations: `agent create`, `edit`, `validate`,
`migrate`, `set-default`, and `list`. `agent migrate --force` warns that it
can destructively affect existing global agents.
- The CLI has an MCP-management surface (`mcp add/remove/list/import/status`).
The installed help does not expose a native Kiro “plugin” command; that
capability must be rechecked when it lands rather than inferred from CAO's
separate server-plugin system.

Current CAO facts:

- The Kiro provider's command builder maps CAO's `kas` label to
`kiro-cli --v3 chat`; it does not model `v3` as the engine name or use the
advertised `--agent-engine v3` selector.
- The v2 launch path unconditionally supplies `--trust-all-tools` to prevent
headless subagent approval prompts from blocking `handoff` and `assign`.
Its legacy-UI fallback, paste timing, status regexes, and response extraction
were developed against the v2 TUI.
- The built-in Kiro memory plugin writes
`/.kiro/steering/cao-memory.md` after `post_create_terminal`. It assumes
Kiro loads all Markdown files in that directory.
- CAO plugins are post-operation observers today; they cannot alter launch,
handoff, or agent configuration. This is distinct from any future Kiro-native
plugin contract.

## Proposed Direction

Make an explicitly named `v3` engine the default for new `kiro_cli` terminals,
while retaining an explicit, supported v2 compatibility selection for existing
users until v3 parity is proven. Resolve the concrete invocation from the
installed CLI's advertised capabilities, preferring one documented canonical
form and testing any equivalent form separately.

Treat this as an end-to-end provider migration rather than a launch-flag
change. A v3-ready provider must:

1. Create and restore v3 terminals with version-aware capability detection.
2. Complete `handoff`, `assign`, and `send_message` without human approval
prompts, dropped input, or false completion.
3. Create, validate, migrate, and preserve existing agents safely.
4. Load steering predictably for the first v3 turn and preserve user-owned
steering content.
5. Define the supported v3 behavior for hooks, MCP configuration, and the
incoming Kiro plugin surface.

## Gaps in PR #470

| Area | Gap | Required outcome |
|---|---|---|
| Default and naming | Default remains v2; the public enum is `v2|kas`, while current Kiro help calls the engine `v3`. | New Kiro sessions select `v3` by default; deprecated aliases, if retained, are documented and telemetry-visible. |
| Launch contract | The v3 branch launches only via `--v3`; it does not validate or select the advertised `--agent-engine v3`, `--mode`, or v3 cloud behavior. | One capability-driven launch contract, with actionable errors for unsupported CLI versions and a tested explicit v2 fallback. |
| Handoff and delivery | Existing parsing and paste behavior target v2 TUI markers. No v3 live fixtures or end-to-end evidence establishes worker readiness, prompt submission, permission handling, completion, cancellation, or reuse. | A v3 transcript corpus plus gated live tests for supervisor-to-v3 and v3-to-v3 `handoff`, `assign`, and `send_message`, including retry/cancel and resumed terminals. |
| Agent files and migration | PR #470 does not use the CLI's `agent create/validate/migrate/set-default` workflow. The follow-on profile branch renders a separate `.kas.json` artifact, but does not establish that Kiro v3 discovers it or safely converts existing agents. | An idempotent migration with dry-run, validation, backup/rollback guidance, collision handling, and an explicit policy for the default agent. Preserve v2 agents until v3 validation succeeds. |
| Permission model | The follow-on branch compiles a CAO policy into an assumed KAS/Cedar JSON shape. That is a useful experiment, not proof that the installed v3 CLI enforces the generated artifact. | Verify the actual v3 agent schema and enforcement with negative tests for denied tools, scoped MCP tools, unrestricted profiles, and `--trust-all-tools`. |
| Steering | The current memory plugin assumes `.kiro/steering` is consumed and writes after terminal creation. Whether a v3 agent reads it before its first prompt, watches changes, or uses a different contract is unverified. | Confirm v3 steering discovery/timing; write before the agent starts when necessary; preserve user files and test first-turn, subsequent-turn, and concurrent-terminal behavior. |
| Hooks | Hooks are passed through profile rendering, but no v3 hook schema, lifecycle semantics, error policy, or test coverage is established. | Either map and test supported v3 hooks or reject them clearly during validation; do not silently serialize unsupported hooks. |
| MCP and plugins | CAO has profile-based MCP injection and observer-only CAO plugins, but no compatibility contract for v3 MCP startup or the incoming Kiro-native plugin feature. | Test MCP startup/failure and CAO handoff tools in v3. Add a separately version-gated adapter for Kiro-native plugins once its official schema and lifecycle are available; keep CAO plugins independent. |
| Operations and docs | The Kiro guide still presents v2 as the default and describes only the Phase 0 refusal. | Update launch, upgrade, rollback, troubleshooting, compatibility matrix, and release notes before flipping the default. |

## Why This / Alternatives Considered

**Chosen: staged default flip with explicit v2 escape hatch.** This makes v3
the product direction while allowing a fast, observable rollback for a CLI
whose UI and agent lifecycle are still changing.

**Alternative: keep v2 default and leave v3 opt-in.** Lower near-term risk, but
it indefinitely postpones validation of the behavior users will eventually
depend on and leaves new Kiro capabilities outside the normal CAO path.

**Alternative: only rename `kas` to `v3` and change the flag.** This is
insufficient: it hides unverified agent schema, orchestration, steering, hook,
and extension behavior behind a default change.

## Value & Success Signal

The default Kiro path is v3, and a supported Kiro CLI version can complete a
representative multi-agent workflow without manual terminal interaction.

Success signals:

- Gated live v3 integration tests pass for all three orchestration primitives
across fresh and reused terminals.
- Agent migration is idempotent and validates every generated v3 artifact;
migration failures leave the prior v2 agent usable.
- Negative permission and MCP-startup tests prove that restrictions fail closed.
- Steering is visible on the first v3 turn in a clean workspace.
- No unexplained increase in Kiro terminal initialization, handoff timeout, or
permission-prompt failure rates after the default flip.

## Risks & Open Questions

- **Strongest objection:** Kiro v3's agent schema and plugin contract may still
change, making a default flip premature. Mitigation: capability/version gates,
live contract tests, and explicit v2 selection.
- **Riskiest assumption:** `--v3` and `--agent-engine v3` are operationally
equivalent in non-interactive, agent-profile, MCP, and resume scenarios.
Validate both only to select a single canonical launch form.
- **Unverified:** The exact v3 schemas for agent files, steering, hooks, and
native plugins. Do not treat the current `.kas.json`/Cedar renderer as
authoritative until validated against released Kiro v3 documentation and
real CLI behavior.
- **Unverified:** Whether `--trust-all-tools` retains the same security and
approval semantics in v3. The current CAO reliance on it must be explicitly
re-evaluated rather than carried forward automatically.

## Rough Scope / Next Step

Start with a compatibility spike against a pinned Kiro CLI v3-capable release:
record fresh/reused v3 terminal transcripts; run the three orchestration
primitives; create and validate a disposable agent; verify first-turn steering,
MCP startup, and the supported hook behavior. Use that evidence to define the
canonical v3 agent artifact and launch command before changing the default.

Then implement behind a version-gated feature flag, publish the v2 rollback
path, and flip the default only when the success signals above are automated.

## Evidence

- Local CLI probe on 2026-08-17: `kiro-cli --version`, `kiro-cli chat --help`,
and `kiro-cli agent --help` using Kiro CLI `2.17.0`.
- PR #470, merged as `6b1978f` (`feat(kiro): add explicit v2/KAS engine
selection`), plus its Phase 0 review follow-up `c5d4235`.
- Follow-on branch `origin/feat/kiro-v3-phase1-profiles`, reviewed for its
profile renderer and launch guard; it is not evidence of released Kiro v3
schema enforcement.

Start with the pinned Kiro CLI compatibility spike: run `kiro-cli --version`, `kiro-cli chat --help`, and `kiro-cli agent --help`, then record fresh and reused v3 terminal transcripts. Exercise `handoff`, `assign`, and `send_message`, plus disposable-agent validation, first-turn steering, MCP startup, and hooks. Done means the evidence defines a canonical launch command and agent artifact before any default flip.

Written by the indexing model from the issue text.