feat(adapter/kiro): first-class Kiro CLI skill runtime

[Alexhans]

Summary

• Bring Kiro CLI (the rebranded Amazon Q Developer CLI — the subject of
  feat(adapter/amazon-q): Amazon Q Developer CLI skill runtime #320) to first-class parity with Claude Code and OpenCode as a skill runtime,
  following the docs/adapters/add-a-harness.md recipe (docs(adapters): add "add a new agent harness" step-by-step recipe #741).
• Discovery: Kiro reads .kiro/skills/ (not .agents/skills/), so this adds
  a kiro row to the skills/setup/agents.md registry plus the per-skill
  relays. The registry-driven adopt/verify/worktree-init logic then wires Kiro
  automatically; .agents / .github / .kiro all carry the 69 magpie-*
  relays.
• Enforcement (agent-harness score: Kiro now 5/5 substrate tools):
  agent-guard (--kiro preToolUse adapter), sandbox-lint (--kiro),
  permission-audit (audit-kiro), agent-isolation (kiro-iso), and spec-loop
  (headless kiro-cli chat --no-interactive) all support Kiro.

Context

#320 was filed for "Amazon Q Developer CLI"; Amazon Q was rebranded to Kiro
CLI, and the issue's suggested ~/.aws/amazonq/agents/<name>.json path is
superseded by Kiro's .kiro/skills/ + agent-config model — this PR implements
current Kiro.

Kiro's permission model is an allowlist/denylist (toolsSettings.shell
allowedCommands / deniedCommands = \A..\z-anchored regex, deny-before-allow,
denyByDefault, autoAllowReadonly) rather than OpenCode's per-command decision
map; the sandbox-lint / permission-audit invariants resolve through that. The
agent-guard adapter shares the harness-agnostic dispatch() core, so verdicts
are byte-identical across harnesses.

This follows the path paved by the OpenCode harness-adapter PRs (#686, #687,
#688) — the same shared-dispatch() / thin-adapter pattern applied to a third
harness. This is a a single PR (rather than OpenCode's incremental slices)
because Kiro additionally needs discovery wiring — the skills/setup/agents.md
registry row plus the per-skill relays — that OpenCode did not require (OpenCode
reads .agents/skills/ for free).

Type of change

• Python package (tools/*/ with pyproject.toml)
• Tool / bridge contract (tools/<system>/*.md)
• CI / dev loop (prek, validators)
• Documentation (docs/, tool READMEs)

Test plan

• prek run --all-files passes
• uv run pytest for each touched package (agent-guard, sandbox-lint,
  permission-audit, agent-isolation, symlink-lint) passes; ruff + mypy clean
• spec-loop tests/test_runner_fixtures.sh covers the Kiro launch argv
  (kiro-cli chat --no-interactive <prompt>, no --model)
• Discovery proven: a fresh kiro-cli chat --no-interactive discovers
  all skills with the .kiro/skills/ relays present, and 0 without
  (negative control); symlink-lint verifies the relays are cycle-free and
  target-correct
• agent-guard proven end-to-end: a real .kiro preToolUse hook
  blocks a Co-Authored-By commit (commit not created) and allows a
  clean one
• vendor-neutrality-score regenerates with Kiro at 5/5 substrate tools
• Real-adopter end-to-end: adopted this branch into a downstream repo (Apache
  Airflow fork) via /magpie-setup — it auto-wired .kiro/skills/, and Kiro
  loaded and invoked framework skills with no gotchas (default-agent auto-load)
• Custom agents covered too: verified on kiro-cli 2.11.1 that skills auto-load
  for both default and custom agents — /context show shows the CLI injecting
  workspace .kiro/skills/*/SKILL.md + global ~/.kiro/skills/*/SKILL.md with no
  explicit skill:// resource. (The kiro.dev docs mention custom agents may need
  resources: [skill://…]; this CLI version does not require it.)

Known limitations

• agent-isolation covers the env -i credential-strip launcher (unit-tested);
  the bubblewrap OS-sandbox layer is not exercised in CI (unprivileged user
  namespaces unavailable in the dev environment) — deferred to a bwrap-capable
  host, consistent with how OpenCode's OS-sandbox layer is treated.
• The sandbox-lint / permission-audit --kiro config-posture checks ship
  alongside the agent-guard hook as defense-in-depth (OpenCode precedent). A
  general /magpie-setup auto-installer for non-Claude harness enforcement is
  out of scope here (Claude-only today; a follow-up would cover OpenCode + Kiro
  together).

---

Gen-AI disclosure: authored with Kiro CLI (Opus 4.8) and reviewed by me.
Commits carry a Generated-by: trailer; no AI Co-Authored-By.

[justinmclean]

Nice, focused harness addition. The thin-adapter-over-shared-dispatch() pattern is
applied cleanly across all five substrate tools, the 69 .kiro relays match the existing
.agents/.claude/.github convention, and the test coverage is strong (including the
differential --kiro/--opencode verdict test). A couple of small observations, neither blocking.

Smaller observations

• tools/permission-audit/src/permission_audit/cli.py — _cmd_audit_kiro reads the Kiro config through _read_opencode_config(...). It's functionally a generic JSON read, but the OpenCode-named helper on the Kiro path reads as a copy-paste artifact. A harness-neutral name (_read_json_config) would make audit-kiro self-documenting.

• tools/sandbox-lint/src/sandbox_lint/kiro.py and
  tools/permission-audit/src/permission_audit/kiro.py duplicate effective_shell_decision,
  _regex_fullmatch_any, and the SHELL_TOOL_NAMES/WILDCARD_TOOL_NAMES/EXFIL_TOOLS
  constants near-verbatim. This tracks the existing per-tool duplication of the OpenCode
  logic, so it's consistent with keeping the tool packages independently installable —
  raising it only so the choice is deliberate rather than accidental.

This review was drafted by an AI-assisted tool and confirmed by a Magpie
maintainer. The findings below are observations, not blockers; a Magpie
maintainer — a real person — will take the next look at the PR. If you think a
finding is mis-applied, please reply on the PR and a maintainer will weigh in.

[potiuk]

Thanks for this, @Alexhans — a substantial and careful piece of work. The adapters faithfully mirror the established OpenCode thin-adapter / shared-dispatch() pattern, sandbox_lint/kiro.py models Kiro's deny-before-allow \A..\z-anchored regex semantics correctly (nice use of re.fullmatch + defensive handling of malformed config), and every adapter ships tests. The 69 relay symlinks + registry row are the bulk of the diff and look mechanical and correct.

The one thing between this and a green light is CI: the required CodeQL check is failing on two alerts, flagged inline below. One is a trivial test-only import fix; the other is a defensible false positive that still needs an explicit resolution to turn the check green. I've also left one non-blocking naming nit.

Once CI is green I'm happy to take another pass. Nice work bringing Kiro to parity.

---

This review was drafted by an AI-assisted tool and confirmed by a Magpie maintainer. The findings below are observations, not blockers; a Magpie maintainer — a real person — will take the next look at the PR. If you think a finding is mis-applied, please reply on the PR and a maintainer will weigh in.

More on how Magpie handles maintainer review: CONTRIBUTING.md.

[potiuk]

I rebased this onto latest main and reconciled the overlaps with the two harness-adapter PRs that merged since you opened this:

• agent-guard __init__.py: combined your kiro_main() + --kiro routing with feat(agent-guard): add harness-neutral --check and --exec CLI modes #765's --check/--exec modes and the Segment basename-normalization fix — all four adapters (Claude/OpenCode/Kiro + check/exec) coexist.
• agent-isolation agent-iso.sh / README: combined your kiro-iso entry with feat(agent-isolation): expose harness-agnostic agent-iso entry point #764's generic agent-iso <cli> entry point and the no-push-gate posture note.
• vendor-neutrality.md: regenerated via vendor-neutrality-score --in-place (agent-isolation is now agnostic per feat(agent-isolation): expose harness-agnostic agent-iso entry point #764, so it moved out of the Kiro/OpenCode-specific lists into any harness; Kiro lands at 4 enforcement tools alongside OpenCode).
• CodeQL refactor(README): slim to overview + skill index + condensed lifecycle #32 (dual import in test_kiro.py): fixed by consolidating onto the from agent_guard import … line.

The remaining CodeQL alert (#31, clear-text logging in sandbox_lint/__init__.py) is a false positive — the flagged print(f" - {e}") is byte-identical to the pre-existing _lint_opencode path CodeQL already accepts; it only fires because the Kiro copy is new code. Dismissing it as such. Local pytest for all five touched packages + ruff/mypy pass. Thanks @Alexhans.

[potiuk]

Approving. This brings Kiro CLI to first-class parity following the add-a-harness recipe, and the adapters faithfully mirror the established OpenCode thin-adapter / shared-dispatch() pattern across agent-guard, sandbox-lint, permission-audit, agent-isolation, and spec-loop, with tests for each. I rebased it onto main and reconciled the overlaps with #764 (agnostic agent-isolation) and #765 (agent-guard --check/--exec + Segment fix); regenerated vendor-neutrality.md; fixed the CodeQL dual-import (#32); and dismissed the CodeQL logging alert (#31) as a false positive (byte-identical to the accepted OpenCode/Claude lint paths). Local pytest for all five packages + ruff/mypy pass.

One non-blocking follow-up (my earlier note): permission-audit's _cmd_audit_kiro reads the Kiro config via _read_opencode_config — a shared _read_json_config helper would read cleaner. Thanks @Alexhans.

---

This review was drafted by an AI-assisted tool and confirmed by a Magpie maintainer. The maintainer approving this PR has read the findings and signed off.

More on how Magpie handles maintainer review: CONTRIBUTING.md.

[Alexhans]

Hey, thanks for this. Sorry I've been unable to look and address the PR comments and create a new revision yesterday. I'll address any leftover comments in my next session.