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

[fanhongy]

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
  <cwd>/.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`.
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 feat(kiro): add explicit v2/KAS engine selection #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.