Follow up Kiro CLI upstream updates: v3 Early Access (permissions.yaml, standalone hooks, Markdown agents with tag-based tools)

[dyoshikawa]

Summary

Kiro CLI v3 (Early Access) — shipped as version 2.8.0 on 2026-06-17, opt-in via kiro-cli --v3 — replaces the surfaces rulesync's kiro-cli target maps. The v2.x agent-config JSON that rulesync emits remains the default and valid until a user opts in, so this is forward-looking: add v3-mode variants alongside the existing v2 adapters rather than replacing them.

Recent Releases

• CLI v3 Early Access (v2.8.0, 2026-06-17): https://kiro.dev/changelog/cli/2-8/
• v3 docs: https://kiro.dev/docs/cli/v3/ ; agent config: https://kiro.dev/docs/cli/v3/agent-config/ ; permissions: https://kiro.dev/docs/cli/v3/permissions/
• Hooks (updated 2026-06-05): https://kiro.dev/docs/cli/hooks/

Gaps

• permissions — v3 capability-based permissions.yaml not emitted. v3 replaces the trust model with capability rules in ~/.kiro/settings/permissions.yaml (user) and ~/.kiro/workspace-roots/<hash>/permissions.yaml (workspace): each rule has capability (fs_read, fs_write, shell, web_fetch, web_search, mcp, subagent, skill, diagnostics, context, all), match, exclude, and effect (deny/ask/allow, resolved by restrictiveness). rulesync's kiro-permissions.ts writes v2-style allowedTools/toolsSettings into .kiro/agents/default.json and explicitly drops ask ("Kiro permissions do not support 'ask'"), which v3 natively supports. Source: https://kiro.dev/docs/cli/v3/permissions/
• hooks — v3 standalone .kiro/hooks/*.json not emitted. v3 stores hooks as standalone .kiro/hooks/*.json files (versioned schema, shell + agent-prompt action types). rulesync emits an embedded hooks block into .kiro/agents/default.json (v2). Source: https://kiro.dev/docs/cli/v3/ , https://kiro.dev/docs/cli/hooks/
• subagents — v3 agent format (Markdown frontmatter, tag-based tools, inline permissions) not emitted. v3 agents are Markdown-with-frontmatter (or JSON) with tools as category tags (read/write/shell/web/subagent/knowledge/*), inline mcpServers, and an inline permissions block. rulesync emits v2 JSON with explicit tool IDs only. Source: https://kiro.dev/docs/cli/v3/agent-config/
• mcp — v3 inline-in-agent embedding not emitted (minor). v3 lets agents embed mcpServers inline for portability; legacy .kiro/settings/mcp.json is still read, so this is lowest-priority and ties into the subagent gap. Source: https://kiro.dev/docs/cli/v3/agent-config/

rules (.kiro/steering/), ignore (.kiroignore), commands (.kiro/prompts/), and skills (.kiro/skills/) are unchanged in v3 — no gaps there.

Proposed Follow-up

• Add v3-mode variants of the kiro-cli permissions/hooks/subagents (and optionally MCP) adapters, gated so they emit the v3 surfaces (permissions.yaml, .kiro/hooks/*.json, Markdown agents with tag-based tools + inline permissions). Keep the v2 adapters as the default for non-opted-in users. In the v3 permissions mapping, map allow/ask/deny directly (stop dropping ask) and map webfetch/websearch patterns to web_fetch/web_search capabilities with match.

References

• https://kiro.dev/changelog/cli/2-8/ — v3 Early Access release (v2.8.0, 2026-06-17), the trigger for this follow-up.
• https://kiro.dev/docs/cli/v3/agent-config/ — v3 Markdown/JSON agent format, tag-based tools, inline permissions/mcpServers.
• https://kiro.dev/docs/cli/v3/permissions/ — v3 capability-based permissions.yaml model.
• https://kiro.dev/docs/cli/hooks/ — v3 standalone .kiro/hooks/*.json hook schema.

[dyoshikawa]

Triage (2026-06-24): keeping open as a tracked follow-up — forward-looking, not yet actionable for default users.

Kiro CLI v3 is Early Access (v2.8.0, 2026-06-17), opt-in via kiro-cli --v3. The v2.x agent-config JSON that rulesync's kiro-cli target emits remains the default and valid surface until a user opts in, so v3 support is additive/forward-looking rather than a correctness gap today.

The proposed work is substantial — v3-mode variants of the permissions (permissions.yaml), hooks (.kiro/hooks/*.json), and subagents (Markdown agents with tag-based tools + inline permissions) adapters, gated alongside the existing v2 adapters, plus mapping ask directly (v3 supports it natively where v2 dropped it). Deferring until v3 stabilizes out of Early Access (so we don't chase a moving schema) and the dual-emit gating design is decided. Leaving open to track.

[dyoshikawa]

Upstream update (re-check on 2026-06-29)

Additional or changed gaps

This issue tracks the forward-looking v3 surfaces. Separately, the current v2 (default) kiro-cli target is missing global scope for several features that upstream already documents at user level:

• commands — no global scope. Kiro CLI reads user-wide prompts from ~/.kiro/prompts/, but KiroCommand.getSettablePaths ignores global; --global dry-run reports kiro-cli "does not support the feature 'commands'." rulesync supports global commands for other tools. Source: https://kiro.dev/docs/cli/chat/manage-prompts/
• subagents — no global scope. Kiro CLI loads agents from both .kiro/agents/ and ~/.kiro/agents/ (local takes precedence), but KiroSubagent.getSettablePaths ignores global and --global dry-run skips subagents. Source: https://kiro.dev/docs/cli/custom-agents/configuration-reference/

(The global ~/.kiro/skills/ skills gap is already tracked in #2070 and applies to both kiro-cli and kiro-ide.)

Proposed follow-up

• Add global scope (~/.kiro/prompts/, ~/.kiro/agents/) to the v2 kiro-cli commands and subagents adapters, independent of the v3 work in this issue.

References

• https://kiro.dev/docs/cli/chat/manage-prompts/ — global ~/.kiro/prompts/.
• https://kiro.dev/docs/cli/custom-agents/configuration-reference/ — .kiro/agents/ + ~/.kiro/agents/ discovery.
• rulesync source: KiroCommand/KiroSubagent getSettablePaths (ignore global).

[dyoshikawa]

Landed the separate v2 global-scope gap in PR #2102: kiro-cli commands (~/.kiro/prompts/) and subagents (~/.kiro/agents/) now support --global, matching what Kiro CLI already documents at user level.

The headline v3 Early Access ask (permissions.yaml, standalone .kiro/hooks/*.json, Markdown agents with tag-based tools) remains deferred per the earlier triage comment — leaving this open to track that.