Skip to content

feat(acp): let a Kiro CLI choice opt into kiro-cli's v2 engine - #30001

Closed
abhiravg wants to merge 1 commit into
kirodotdev:mainfrom
abhiravg:feat/kiro-cli-engine-v2-opt-in
Closed

abhiravg wants to merge 1 commit into
kirodotdev:mainfrom
abhiravg:feat/kiro-cli-engine-v2-opt-in

Conversation

@abhiravg

@abhiravg abhiravg commented Nov 4, 2026 •

Copy link
Copy Markdown

Problem / Motivation

Goal: A person whose Agent Harness is Kiro CLI can choose to keep kiro-cli's V2 engine until kiro-cli removes it, while the default stays exactly as the 2026-10-28 decision describes.

On kiro-cli 3.0.0, a bare kiro-cli acp starts the V3 engine, although its --help still says "v2 when neither is set". Measured on an aarch64 Linux host with kiro-cli 3.0.0: an ACP initialize against kiro-cli acp returns the V3 capability block (_kiro/... extension methods); the same call against kiro-cli acp --agent-engine v2 returns a plain agentInfo {name: "Kiro CLI Agent", version: "3.0.0"}. Combined with docs/decisions/2026-10-28-a-kiro-cli-choice-runs-on-kas.md, every Kiro CLI choice now runs on V3, and there is no way back to V2.

This needs @buluoray's sign-off. It narrows a recorded decision, which AGENTS.md (§ Specs and docs) and docs/decisions/README.md rule 3 say only a maintainer may do. A draft superseding entry is at the end of this description for the owner to approve, edit or reject.

Why it matters

V3 has an open defect that hits Kiro CLI users today: sub-agents receive the parent session's context and skill catalog (internal ticket P554087731). People who depend on isolated sub-agents have no workaround while every Kiro CLI choice runs V3. #20450 asked for the explicit --agent-engine v2 pin before the default flip; this delivers it as an opt-in instead of a default.

Not a goal

  • Changing the default. "auto" is today's behaviour, byte for byte.
  • The KAS harness. It keeps --agent-engine v3 and never reads the setting.
  • Fixing the V3 sub-agent defect itself.
  • Keeping V2 alive after kiro-cli removes it: the option turns itself off then.
  • Writing the superseding decision entry. Rule 4 of docs/decisions/README.md lets an agent add an entry only for a decision a maintainer already made, so the entry is drafted below rather than committed.

What changed (motivation → approach → change)

New setting agent.kiro_cli_engine: auto (default) or v2.

  • auto: nothing moves. A Kiro CLI choice runs on KAS once kiro-cli is confirmed to offer V3, and on the V2 launch otherwise.
  • v2: the Kiro CLI choice stays on the Kiro CLI harness, and kiro-cli starts with --agent-engine v2. The flag is added only while the pinned kiro-cli's acp --help lists V2, read by a cached probe that never runs a binary found on PATH. If kiro-cli has no engine selector, the probe can't run, or V2 is retired, the command is unchanged and the reason is logged once. Once kiro-cli is known to have retired V2, the choice follows auto again.

The rule applies everywhere a Kiro CLI choice is resolved or launched: both command builders, a crewmate's own kiro pin, the gateway's startup check and the per-process check outside the gateway. The "Kiro CLI now runs on Kiro Agent" note and its one-click "save KAS" button stay quiet for a v2 user, because the choice no longer resolves to KAS. kirocrew doctor prints an engine row.

The setting is read once per process, so a save reaches the choice and the launch together at the next restart. Settings → Agent Harness → Kiro CLI shows "Engine: Automatic / V2 (until kiro-cli removes it)". The setting needs a restart, and the card says so after a save. All 12 catalogs carry the new strings.

Where: src/kiro_crew/kiro_cli_engine.py (new: the setting's values and the command flag), kiro_cli.py (acp_agent_engines_at), agent_sdk/backends.py (kiro_cli_pick_backend(engine), record_kiro_cli_v2_evidence), config/sections_agent.py, config/loader_builders.py, config/loader_document.py (field, loader, document reader), platform/bootstrap.py (gateway check), crewmate_harness.py, acp/harness/kiro.py and acp/client_start.py (the two command builders), cli_doctor.py + cli_doctor_parts/kas_relay.py (engine row), dashboard/handlers/core_config_schema.py (PATCH schema), config-baseline.json (regenerated), website/src/pages/developer/KiroCliEngineCard.tsx + AgentBackendTab.tsx (UI), website/src/i18n/locales/* (strings).

Owning specs updated in this commit: harness-parity H1, H9 and H17, the harness-choice record in config.md, and the Kiro CLI launch line in acp-client.md.

Backwards compatibility

Compatible: the setting is new and defaults to auto, which follows the same code path as main. No stored value changes meaning, and the schema accepts only auto and v2.

Removes nothing: no field, path, validator or behaviour that main accepts is narrowed. The KAS move is skipped only for a user who saves v2.

Tests

  • test/test_kiro_cli_engine.py (52 tests):
    • the engine flag for unset, auto and v2 on both KiroHarness.resolve_spawn and the AcpClient Kiro path
    • an old kiro-cli without the selector, a kiro-cli that retired V2, and an unknown probe all keep today's command
    • a binary that isn't the pinned one is never probed
    • a kiro-cli seen at spawn without v2 is recorded, so the next load follows auto
    • the startup check's acp --help result is reused, so the engine read spawns nothing extra
    • the setting is read once per process: a save while running moves neither the choice nor the command until restart
    • kirocrew doctor keeps its KAS rows when a policy moved a v2 Kiro CLI choice onto KAS
    • the acp --help parser and cache
    • auto with confirmed V3 still runs on KAS, so it is unchanged from main
    • v2 keeps the choice on Kiro CLI, including the provider factory, the crewmate pin (H17) and the per-process check
    • v2 on a kiro-cli that retired V2 follows auto
    • the save-KAS offer is silent for v2
    • a PATCH accepts auto/v2 and refuses v3, v1, V2, "", 2 and null with a 400, writing nothing
    • the dataclass default and restart mark
  • website/src/test/KiroCliEngineCard.test.tsx: the stored value shown, the temporary V2 label, the PATCH on pick, no write when the stored value is picked again, restart-pending after a save, inline error on a failed save.
  • website/src/test/AgentBackendTab.detailCard.test.tsx: the picker renders in the Kiro CLI detail only.
  • Existing suites rerun green: test_acp_harness_contract, test_acp_backend_kas, test_acp_client_binary_resolution, test_crewmate_harness, test_kas_cli_floor, test_kiro_on_kas_notice, test_harness_parity, test_cli_chat, test_config_baseline, test_config_schema, test_cli_doctor_parts, the usage-scrape suites and the AgentBackendTab vitest files.
  • Determinism: backend file green in 10 repeats under -n 4 and in a seeded shuffled order (52 passed); the vitest card file green in 5 --sequence.shuffle runs.

Proof: not provable -- other: feat PR, no reverted-hunk proof applies; the auto-unchanged and v2 tests above pin both sides.

Manual verification

Live check on an aarch64 Linux host with kiro-cli 3.0.0, using this branch's command builder against the real pinned binary:

acp engines: ('v2', 'v1', 'v3')
engine=auto argv=['acp'] agentInfo=None has__kiro_ext=True        <- V3
engine=v2 argv=['acp', '--agent-engine', 'v2'] agentInfo={'name': 'Kiro CLI Agent', 'title': 'Kiro CLI Agent', 'version': '3.0.0'} has__kiro_ext=False   <- V2

I couldn't run a full gateway on that Linux host: its sandbox's SQLite has no FTS5 and there is no systemd user bus. So the end-to-end "new session's child runs acp --agent-engine v2" check covers the two command builders, which every session path goes through: sessions, sub-agents (spawn_run), crons, crew and worker sessions, background sessions, session reload/respawn and model switch (providers/acp_runtime_start.py, session_background.py → KiroHarness.resolve_spawn), plus knowledge/llm_pool and the placeholder client (AcpClient's own Kiro path). agent_sdk/pod_child_probe.py's bare acp startup probe carries no session and is unchanged.

Screenshots / video

The images are committed under temp-screenshots/kiro-cli-engine/ (the fork-PR path in .gitignore and docs/ci/ci-and-reviews.md, read by the review lanes) and linked here at the head commit so they render. The Kiro CLI row's new picker, rendered from Storybook with the real schema entry (dark theme). Automatic (default), V2 saved, and the open list:

Engine picker, Automatic

Engine picker, V2 saved

Engine picker, open

Related Issues

Part of #20450

Draft superseding decision entry (for @buluoray)

Proposed file docs/decisions/2026-11-04-a-kiro-cli-choice-may-keep-kiro-clis-v2-engine.md, to be added by or quoting the owner in its own PR, per rule 3:

# A Kiro CLI harness choice may opt to keep kiro-cli's v2 engine until kiro-cli removes it

Decided by: <owner to fill>
Date: <owner to fill>
Supersedes: 2026-10-28-a-kiro-cli-choice-runs-on-kas.md

## Decision
`agent.kiro_cli_engine` "auto" (the default) keeps the 2026-10-28 rule unchanged; "v2" keeps a stored Kiro CLI choice on the Kiro CLI harness, launched with `--agent-engine v2` while the installed kiro-cli offers v2, and follows "auto" once it does not.

## Why
- kiro-cli 3.0 starts a bare `acp` on v3, so every Kiro CLI choice runs v3, and v3 sub-agents receive the parent's context and skill catalog (P554087731).
- #20450 asked for an explicit v2 pin on the Kiro CLI harness.
- The option is temporary: it ends when kiro-cli removes v2.

## Evidence
- <link to the owner's approving comment on this PR>
- https://github.com/kirodotdev/KiroCrew/issues/20450

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@abhiravg
abhiravg requested review from a team and KiroCrewCaptain as code owners November 4, 2026 23:15
@abhiravg
abhiravg requested a review from CrysisDeu November 4, 2026 23:15
@abhiravg

abhiravg commented Nov 4, 2026

Copy link
Copy Markdown
Author

@buluoray, could you review this? It narrows docs/decisions/2026-10-28-a-kiro-cli-choice-runs-on-kas.md, so it needs your sign-off under the AGENTS.md decisions rule. (This fork account can't request reviewers, so I'm asking here.)

The default (auto) is unchanged. The opt-in v2 is labelled temporary and turns itself off once kiro-cli drops V2. A draft superseding entry is at the end of the description: approve it, edit it, or say no. Under docs/decisions/README.md rule 4 I can't commit that entry before you've decided.

needs-a-decision

recorded-decisions-are-not-regressions: this PR narrows the 2026-10-28 Kiro CLI → KAS decision behind an opt-in agent.kiro_cli_engine: v2; auto (default) is unchanged.
The superseding entry is drafted in the PR body and waits for the owner, as rules 3 and 4 of docs/decisions/README.md require.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 4, 2026
Add agent.kiro_cli_engine with "auto" (default) and "v2". "auto" keeps
the 2026-10-28 rule unchanged: a stored Kiro CLI choice runs on the KAS
path once kiro-cli is confirmed to offer v3. "v2" keeps that choice on
the Kiro CLI harness and starts kiro-cli with --agent-engine v2, which
kiro-cli 3.0 needs because a bare "acp" starts v3. The pin is added
only while the pinned kiro-cli's acp --help lists v2; otherwise the
argv is unchanged, and once kiro-cli retires v2 the choice follows
"auto" again.

Covers both Kiro CLI argv builders, the crewmate pin, the gateway floor
and the per-process verdict. Settings > Agent Harness shows the picker
in the Kiro CLI row, labelled temporary. The save-KAS offer stays quiet
for a v2 user because the pick no longer resolves to KAS.

Part of kirodotdev#20450
@abhiravg
abhiravg force-pushed the feat/kiro-cli-engine-v2-opt-in branch from 6f14e36 to acb17f5 Compare November 5, 2026 04:08
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 5, 2026
@abhiravg

abhiravg commented Nov 5, 2026

Copy link
Copy Markdown
Author

Edited the "Problem / Motivation" section at the PR author's request: "Measured on this host" now reads "Measured on an aarch64 Linux host with kiro-cli 3.0.0", so readers know what was measured. The goal and findings are unchanged.

@CrysisDeu

Copy link
Copy Markdown
Contributor

V2 is deprecated

@CrysisDeu CrysisDeu closed this Nov 5, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants