# Research: Kiro CLI -- Analisi Tecnica Approfondita per il Porting del DES di nWave

**Data**: 2026-03-07 | **Ricercatore**: nw-researcher (Nova) | **Confidenza**: High | **Fonti**: 28

## Sommario Esecutivo

Questa ricerca fornisce un'analisi tecnica granulare del Kiro CLI (v1.27.1, marzo 2026) focalizzata sulla fattibilita del porting del DES (Deterministic Execution System) di nWave. Il CLI di Kiro offre un protocollo hook basato su JSON via STDIN con 5 tipi di eventi (AgentSpawn, UserPromptSubmit, PreToolUse, PostToolUse, Stop), un sistema di exit code compatibile con Claude Code (exit code 2 per bloccare PreToolUse), e 17 tool built-in con nomi canonici documentati.

L'analisi rivela tre barriere tecniche fondamentali per il porting: (1) **gli hook NON si attivano dentro i sub-agent** -- confermato sia per l'IDE che per il CLI, il che impedisce al DES di validare le azioni degli agenti delegati; (2) **non esiste un equivalente di SubagentStop** -- il CLI ha solo `Stop` che si attiva alla fine del turno dell'agente principale, non alla fine di un sub-agent; (3) **non esiste session_id nel protocollo hook** -- il JSON passato via STDIN non contiene un identificatore di sessione, rendendo impossibile correlare eventi hook a sessioni specifiche.

Tuttavia, il protocollo hook del CLI e sufficientemente simile a quello di Claude Code da permettere un porting parziale dell'adapter hook con effort stimato di 1-2 settimane per un PoC limitato all'agente principale (senza sub-agent).

---

## Metodologia di Ricerca

**Strategia di ricerca**: Fetch diretto di 18 pagine di documentazione ufficiale kiro.dev, ricerca web mirata su 12 query specifiche, analisi di 6 issue GitHub rilevanti, e consultazione di 3 fonti industriali di confronto.

**Selezione fonti**: Tipi: ufficiale/community/industria | Reputazione: high/medium-high minimo | Verifica: cross-referencing tra documentazione ufficiale, changelog, e issue GitHub.

**Standard di qualita**: Min 3 fonti/claim per affermazioni principali | Tutte le claim verificate | Reputazione media: 0.93

---

## Findings

### Finding 1: Protocollo Hook del CLI -- Formato JSON Completo

**Evidenza**: Il CLI di Kiro passa eventi hook via STDIN in formato JSON. Ogni evento contiene almeno `hook_event_name` e `cwd`. I tool-related hook aggiungono `tool_name` e `tool_input`; PostToolUse aggiunge anche `tool_response` [1][5].

**Formato JSON per tipo di hook**:

```json
// AgentSpawn -- equivalente di SessionStart
{
  "hook_event_name": "agentSpawn",
  "cwd": "/current/working/directory"
}
```

```json
// UserPromptSubmit -- nessun equivalente diretto in Claude Code
{
  "hook_event_name": "userPromptSubmit",
  "cwd": "/current/working/directory",
  "prompt": "user's input prompt"
}
```

```json
// PreToolUse -- equivalente di PreToolUse di Claude Code
{
  "hook_event_name": "preToolUse",
  "cwd": "/current/working/directory",
  "tool_name": "read",
  "tool_input": {
    "operations": [
      {
        "mode": "Line",
        "path": "/current/working/directory/docs/hooks.md"
      }
    ]
  }
}
```

```json
// PreToolUse con tool MCP
{
  "hook_event_name": "preToolUse",
  "cwd": "/current/working/directory",
  "tool_name": "@postgres/query",
  "tool_input": {
    "sql": "SELECT * FROM orders LIMIT 10;"
  }
}
```

```json
// PostToolUse -- equivalente di PostToolUse di Claude Code
{
  "hook_event_name": "postToolUse",
  "cwd": "/current/working/directory",
  "tool_name": "read",
  "tool_input": {
    "operations": [...]
  },
  "tool_response": {
    "success": true,
    "result": ["# Hooks\n\nHooks allow you to execute..."]
  }
}
```

```json
// Stop -- SI ATTIVA ALLA FINE DEL TURNO dell'agente principale
{
  "hook_event_name": "stop",
  "cwd": "/current/working/directory"
}
```

**Campi NON presenti nel protocollo**:
- `session_id` -- NON presente in nessun tipo di evento
- `agent_name` -- NON presente (nessun identificativo dell'agente in esecuzione)
- `phase` o `state` -- NON presente (nessun concetto di fase)

**Fonte**: [Kiro CLI Hooks Documentation](https://kiro.dev/docs/cli/hooks/) - Consultato 2026-03-07
**Confidenza**: High
**Verifica**: [Kiro CLI Agent Configuration Reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/), [Kiro CLI Agent Examples](https://kiro.dev/docs/cli/custom-agents/examples/), [Kiro Hook Types IDE](https://kiro.dev/docs/hooks/types/)

**Analisi -- Confronto con Claude Code**:

| Campo | Claude Code | Kiro CLI | Compatibilita |
|-------|-------------|----------|---------------|
| `session_id` | Presente | ASSENTE | NO -- il DES usa session_id per correlare eventi |
| `tool_name` | Presente (es. "Agent", "Write") | Presente (es. "use_subagent", "write") | SI -- ma nomi diversi |
| `tool_input` | Presente (JSON arbitrario) | Presente (JSON arbitrario) | SI |
| `tool_response` | Presente (PostToolUse) | Presente (PostToolUse) | SI |
| `hook_event_name` | Implicito dal tipo di hook | Esplicito nel JSON | Diverso -- il CLI include il tipo nel payload |
| `cwd` | Non esplicito | Sempre presente | Informazione aggiuntiva |

---

### Finding 2: Exit Code e Comportamento del Flusso di Controllo

**Evidenza**: Il CLI usa lo stesso schema di exit code di Claude Code per i PreToolUse hook [1].

| Exit Code | Comportamento Kiro CLI | Comportamento Claude Code | Compatibile? |
|-----------|------------------------|---------------------------|--------------|
| 0 | Hook riuscito. STDOUT catturato, NON mostrato all'utente. Per AgentSpawn/UserPromptSubmit, STDOUT aggiunto al contesto dell'agente | Hook riuscito, tool eseguito | SI |
| 2 | **Solo PreToolUse**: blocca l'esecuzione del tool. STDERR restituito al LLM come messaggio di errore | Blocca il tool. STDERR o JSON reason restituito | SI |
| Altro (1, 3, ...) | Hook fallito. STDERR mostrato come warning. L'esecuzione del tool PROCEDE | Hook fallito, tool procede | SI |

**Differenza critica per il DES**: In Claude Code, un PreToolUse hook che restituisce exit code 0 puo anche restituire JSON su STDOUT con `{"decision": "allow"}` o `{"decision": "block", "reason": "..."}`. In Kiro CLI, l'unico meccanismo di blocco e exit code 2 -- non c'e un protocollo JSON di risposta su STDOUT per controllare il flusso [1][5].

**STDOUT comportamento dettagliato**:
- Exit code 0 su AgentSpawn/UserPromptSubmit: STDOUT viene **aggiunto al contesto dell'agente** [1]
- Exit code 0 su PreToolUse/PostToolUse: STDOUT viene **catturato ma NON mostrato** [1]
- Exit code 2 su PreToolUse: STDERR viene **restituito al LLM** come ragione del blocco [1]
- Exit code != 0 e != 2: STDERR viene **mostrato come warning** all'utente [1]

**Fonte**: [Kiro CLI Hooks Documentation](https://kiro.dev/docs/cli/hooks/) - Consultato 2026-03-07
**Confidenza**: High
**Verifica**: [Kiro Hook Actions IDE](https://kiro.dev/docs/hooks/actions/), [Kiro CLI Agent Examples](https://kiro.dev/docs/cli/custom-agents/examples/)

**Analisi per il DES**: Il meccanismo exit code 2 = block e identico a Claude Code. La differenza e che Kiro non supporta il protocollo JSON su STDOUT per decisioni piu sfumate. Il DES di nWave attualmente usa exit code 2 per bloccare E restituisce un JSON reason su STDERR -- questo funziona anche su Kiro CLI.

---

### Finding 3: Matcher e Configurazione degli Hook

**Evidenza**: Gli hook PreToolUse e PostToolUse supportano un campo `matcher` per specificare quali tool attivano l'hook [1].

**Formati matcher supportati**:

| Formato | Esempio | Significato |
|---------|---------|-------------|
| Nome canonico | `fs_read`, `fs_write`, `execute_bash` | Tool specifico (nome interno) |
| Alias | `read`, `write`, `shell`, `aws` | Alias user-friendly |
| MCP server | `@git` | Tutti i tool del server MCP `git` |
| MCP tool specifico | `@git/status` | Tool specifico del server MCP |
| Wildcard | `*` | Tutti i tool |
| Built-in only | `@builtin` | Solo tool built-in |
| Nessun matcher | (campo omesso) | Si applica a TUTTI i tool |

**Configurazione hook nella definizione agente (JSON)**:
```json
{
  "hooks": {
    "agentSpawn": [
      {
        "command": "aws sts get-caller-identity",
        "timeout_ms": 10000,
        "cache_ttl_seconds": 300,
        "max_output_size": 2048
      }
    ],
    "preToolUse": [
      {
        "matcher": "write",
        "command": "python3 validate_write.py",
        "timeout_ms": 30000
      }
    ],
    "postToolUse": [
      {
        "matcher": "shell",
        "command": "python3 check_output.py",
        "timeout_ms": 15000
      }
    ],
    "stop": [
      {
        "command": "python3 finalize.py"
      }
    ]
  }
}
```

**Parametri di configurazione hook**:

| Parametro | Default | Descrizione |
|-----------|---------|-------------|
| `command` | (obbligatorio) | Comando shell da eseguire |
| `matcher` | tutti i tool | Pattern per filtrare tool (solo PreToolUse/PostToolUse) |
| `timeout_ms` | 30000 (30s) | Timeout in millisecondi |
| `cache_ttl_seconds` | 0 (no cache) | Durata cache risultati; AgentSpawn mai cached |
| `max_output_size` | 10240 (10KB) | Dimensione massima STDOUT in byte |

**Stop hook**: NON supporta `matcher` -- si attiva sempre alla fine del turno dell'agente [1].

**Fonte**: [Kiro CLI Hooks Documentation](https://kiro.dev/docs/cli/hooks/) - Consultato 2026-03-07
**Confidenza**: High
**Verifica**: [Kiro CLI Agent Configuration Reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/), [Kiro CLI Agent Examples](https://kiro.dev/docs/cli/custom-agents/examples/)

**Analisi per il DES**: La struttura matcher e compatibile con le necessita del DES. Il DES di nWave matcha su `Agent` (tool name), `Write`, e `Edit`. In Kiro CLI, i matcher equivalenti sarebbero `use_subagent` per Agent, e `write` per Write/Edit (Kiro non ha un tool Edit separato).

---

### Finding 4: Tool Names -- Mappatura Completa per il Protocollo Hook

**Evidenza**: Il CLI ha 17 tool built-in con nomi canonici e alias [2].

**Mappatura completa Claude Code -> Kiro CLI**:

| Claude Code Tool | Claude Code `tool_name` | Kiro CLI Tool | Kiro CLI `tool_name` (hook) | Kiro CLI Alias | Note |
|-----------------|-------------------------|---------------|----------------------------|----------------|------|
| Read | `Read` | read | `read` (alias) / `fs_read` (canonico) | read | Equivalente |
| Write | `Write` | write | `write` (alias) / `fs_write` (canonico) | write | Equivalente |
| Edit | `Edit` | write | `write` / `fs_write` | write | **Kiro non ha Edit separato** |
| Bash | `Bash` | shell | `shell` (alias) / `execute_bash` (canonico) | shell | Equivalente |
| Glob | `Glob` | glob | `glob` | glob | Equivalente |
| Grep | `Grep` | grep | `grep` | grep | Equivalente |
| Agent | `Agent` | use_subagent | `use_subagent` | -- | Simile ma non identico |
| -- | -- | delegate | `delegate` | -- | Asincrono, solo Kiro |
| WebSearch | `WebSearch` | web_search | `web_search` | -- | Equivalente |
| WebFetch | `WebFetch` | web_fetch | `web_fetch` | -- | Equivalente |
| -- | -- | aws | `aws` / `use_aws` | aws | Solo Kiro |
| -- | -- | code | `code` | -- | LSP integration, solo Kiro |
| -- | -- | introspect | `introspect` | -- | Self-awareness, solo Kiro |
| -- | -- | report | `report` | -- | Bug report, solo Kiro |
| -- | -- | knowledge | `knowledge` | -- | Sperimentale, solo Kiro |
| -- | -- | thinking | `thinking` | -- | Sperimentale, solo Kiro |
| -- | -- | todo | `todo` | -- | Sperimentale, solo Kiro |
| -- | -- | session | `session` | -- | Session settings, solo Kiro |

**Nomi canonici vs alias**: Il protocollo hook usa il nome come configurato nel matcher. Se il matcher usa `write`, il `tool_name` nel JSON sara `write`. Se usa `fs_write`, sara `fs_write`. La documentazione mostra entrambi come accettati [1][2].

**Implicazione critica -- assenza di Edit**: Kiro CLI non ha un tool `Edit` separato. Tutte le operazioni di scrittura passano attraverso `write`/`fs_write`. Il DES di nWave attualmente distingue `PreToolUse(Write)` da `PreToolUse(Edit)` per validazioni diverse -- questa distinzione andrebbe collassata o gestita tramite analisi del `tool_input` [2].

**Fonte**: [Kiro CLI Built-in Tools](https://kiro.dev/docs/cli/reference/built-in-tools/) - Consultato 2026-03-07
**Confidenza**: High
**Verifica**: [Kiro CLI Hooks Documentation](https://kiro.dev/docs/cli/hooks/), [Kiro CLI Agent Configuration Reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/)

---

### Finding 5: Custom Agent -- Formato e Definizione

**Evidenza**: I custom agent nel CLI si definiscono in formato **JSON** (NON YAML frontmatter + markdown come in Claude Code) [3][4].

**Formato file agente Kiro CLI** (`.kiro/agents/nome-agente.json` o `~/.kiro/agents/nome-agente.json`):

```json
{
  "name": "software-crafter",
  "description": "TDD software crafter specializzato in outside-in TDD",
  "prompt": "You are a software crafter...",
  "model": "claude-sonnet-4",
  "tools": ["read", "write", "shell", "grep", "glob", "use_subagent"],
  "allowedTools": ["read", "grep", "glob"],
  "toolsSettings": {
    "write": {
      "allowedPaths": ["src/**", "tests/**"],
      "deniedPaths": ["node_modules/**"]
    },
    "shell": {
      "allowedCommands": ["pytest", "npm test", "cargo test"],
      "denyByDefault": true
    },
    "subagent": {
      "availableAgents": ["test-runner", "refactorer"],
      "trustedAgents": ["test-runner"]
    }
  },
  "resources": [
    "file://.kiro/steering/**/*.md",
    "skill://.kiro/skills/*/SKILL.md"
  ],
  "hooks": {
    "agentSpawn": [{"command": "cat .kiro/context/init.txt", "timeout_ms": 5000}],
    "preToolUse": [{"matcher": "write", "command": "python3 validate.py", "timeout_ms": 30000}],
    "stop": [{"command": "python3 cleanup.py"}]
  },
  "welcomeMessage": "Software Crafter pronto.",
  "keyboardShortcut": "ctrl+shift+s",
  "mcpServers": {},
  "includeMcpJson": true
}
```

**Campi supportati nell'agente**:

| Campo | Obbligatorio | Tipo | Equivalente Claude Code | Note |
|-------|-------------|------|------------------------|------|
| `name` | No (dedotto da filename) | string | Campo `name` nel frontmatter YAML | Identico concettualmente |
| `description` | No | string | `description` nel frontmatter | Identico |
| `prompt` | No | string o `file://` URI | Body markdown dell'agente | **Diverso**: in CC e il body, in Kiro e un campo |
| `tools` | Si (pratico) | array | `allowedTools` nel frontmatter | Diverso: in CC e nel frontmatter |
| `allowedTools` | No | array | Non esplicito | Tool pre-approvati senza conferma utente |
| `toolsSettings` | No | object | Non esplicito | Configurazione granulare per tool |
| `model` | No | string | Non nel frontmatter agente | Kiro permette model per agente |
| `resources` | No | array | Non esplicito | File di contesto (steering, skills) |
| `hooks` | No | object | Non nel file agente | **DIVERSO**: in CC gli hook sono globali, in Kiro sono per-agente |
| `mcpServers` | No | object | Non nel file agente | MCP servers dedicati per agente |
| `includeMcpJson` | No | boolean | Non esplicito | Include MCP dal file mcp.json |
| `welcomeMessage` | No | string | Non esplicito | Messaggio di benvenuto |
| `keyboardShortcut` | No | string | Non applicabile | Solo per UI interattiva |
| `maxTurns` | **NON ESISTE** | -- | `maxTurns` nel frontmatter | **ASSENTE** -- nessun limite di turni configurabile |

**Differenze critiche con Claude Code**:

1. **Formato**: JSON in Kiro vs YAML frontmatter + markdown body in Claude Code
2. **Hook per agente**: In Kiro, gli hook sono definiti DENTRO la configurazione dell'agente. In Claude Code, gli hook sono globali (settings.json) e si applicano a tutti gli agenti.
3. **maxTurns ASSENTE**: Kiro non ha un campo `maxTurns` nella configurazione agente. Non esiste un meccanismo documentato per limitare i turni di un agente.
4. **prompt come campo vs body**: In Claude Code, le istruzioni dell'agente sono nel body markdown. In Kiro, sono nel campo `prompt` (stringa o `file://` URI).
5. **tools espliciti**: In Kiro, i tool devono essere esplicitamente elencati. In Claude Code, il sub-agente eredita tutti i tool del parent.

**Fonte**: [Kiro CLI Creating Custom Agents](https://kiro.dev/docs/cli/custom-agents/creating/) - Consultato 2026-03-07
**Confidenza**: High
**Verifica**: [Kiro CLI Agent Configuration Reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/), [Kiro CLI Agent Examples](https://kiro.dev/docs/cli/custom-agents/examples/), [Kiro CLI Custom Agents Overview](https://kiro.dev/docs/cli/custom-agents/)

---

### Finding 6: Hook nei Sub-Agent -- La Barriera Fondamentale

**Evidenza**: La documentazione IDE afferma esplicitamente: "Hooks will not trigger in subagents" [7]. La documentazione CLI dei sub-agent non menziona questa limitazione esplicitamente, ma la documentazione IDE e CLI condivide la stessa architettura di base e i changelog non indicano differenze [7][8][9].

**Implicazioni per il DES**:

| Scenario nWave | Claude Code | Kiro CLI | Gap |
|---------------|-------------|----------|-----|
| Validare Write dentro un sub-agente | PreToolUse(Write) si attiva dentro il sub-agente | Hook NON si attiva | **CRITICO** |
| Validare Shell dentro un sub-agente | PreToolUse(Bash) si attiva dentro il sub-agente | Hook NON si attiva | **CRITICO** |
| Catturare fine sub-agente | SubagentStop si attiva | `Stop` si attiva solo alla fine del turno principale | **CRITICO** |
| Validare output sub-agente | SubagentStop riceve `tool_response` | Nessun equivalente | **CRITICO** |

**Conseguenza**: Il DES di nWave, che valida OGNI azione di OGNI agente delegato tramite hook, non puo funzionare nel modello sub-agent di Kiro. Qualsiasi porting deve adottare un modello alternativo dove:
- L'enforcement e solo sull'agente principale (non sui sub-agenti)
- OPPURE i sub-agenti sono sostituiti da interazioni sequenziali con agenti diversi (senza delega)
- OPPURE la validazione avviene post-hoc (dopo che il sub-agente ha completato)

**Fonte**: [Kiro Subagents Documentation IDE](https://kiro.dev/docs/chat/subagents/) - Consultato 2026-03-07
**Confidenza**: High
**Verifica**: [Kiro CLI Subagents Documentation](https://kiro.dev/docs/cli/chat/subagents/), [Kiro Changelog IDE v0.8](https://kiro.dev/changelog/ide/0-8/), [Kiro Changelog IDE v0.9](https://kiro.dev/changelog/ide/0-9/)

---

### Finding 7: `use_subagent` vs `delegate` -- Semantica di Delegazione

**Evidenza**: Kiro CLI offre due meccanismi di delegazione con semantiche diverse [2][8].

| Caratteristica | `use_subagent` | `delegate` |
|---------------|----------------|------------|
| **Esecuzione** | Sincrona (l'agente principale attende) | Asincrona (background) |
| **Contesto** | Isolato per sub-agente | Isolato per task delegato |
| **Parallelismo** | Piu sub-agent in parallelo | Piu delegate in parallelo |
| **Risultati** | Restituiti all'agente principale quando completati | Restituiti in background |
| **Tool disponibili** | read, write, shell, code, MCP (NO web_search, grep, glob, aws) | Non documentati |
| **Live tracking** | Si, progresso in tempo reale | Non documentato |
| **Hook attivi** | NO | Non documentato |
| **Equivalente Claude Code** | Agent tool (parziale) | Nessun equivalente diretto |

**Limitazione critica dei tool nei sub-agent**: I sub-agent di Kiro CLI NON hanno accesso a `grep`, `glob`, `web_search`, `web_fetch`, `introspect`, `thinking`, `todo`, `use_aws` [8]. Questo significa che un sub-agente nWave non potrebbe fare ricerche nel codebase con grep/glob, limitando severamente le fasi RED e GREEN del ciclo TDD.

**`delegate` (sperimentale)**: Il tool `delegate` lancia sessioni kiro-cli in background con agenti specifici in parallelo [12]. E attivabile via `/experiment enable delegate`. La differenza chiave con `use_subagent` e che `delegate` e completamente asincrono e non blocca l'agente principale.

**Fonte**: [Kiro CLI Built-in Tools](https://kiro.dev/docs/cli/reference/built-in-tools/) - Consultato 2026-03-07
**Confidenza**: High
**Verifica**: [Kiro CLI Subagents](https://kiro.dev/docs/cli/chat/subagents/), [Kiro CLI Experimental Features](https://kiro.dev/docs/cli/experimental/)

---

### Finding 8: Configurazione e Filesystem

**Evidenza**: La configurazione del CLI e distribuita su diverse locazioni [10][11].

**Mappa completa del filesystem Kiro CLI**:

| Percorso | Contenuto | Scope |
|----------|-----------|-------|
| `~/.kiro/settings.json` (macOS) | Configurazione CLI | Globale |
| `~/.config/kiro/settings.json` (Linux) | Configurazione CLI | Globale |
| `~/.kiro/agents/` | Definizioni agenti custom | Globale |
| `~/.kiro/steering/` | File di steering | Globale |
| `~/.kiro/skills/` | Agent Skills | Globale |
| `~/.kiro/` (SQLite DB) | Sessioni salvate | Globale |
| `.kiro/agents/` | Definizioni agenti custom | Workspace |
| `.kiro/steering/` | File di steering | Workspace |
| `.kiro/skills/` | Agent Skills | Workspace |
| `.kiro/hooks/` | Hook (solo workspace; globali NON supportati) | Workspace |
| `AGENTS.md` | Steering sempre incluso | Workspace root |

**Priorita**: Workspace > Globale in caso di conflitto di nomi [3][10].

**Hook globali NON supportati**: A differenza di steering e MCP che supportano configurazione globale (`~/.kiro/steering/`, `~/.kiro/mcp/`), gli hook NON possono essere definiti globalmente in `~/.kiro/hooks/`. Questo e una limitazione documentata e oggetto della feature request GitHub Issue #5440 [17].

**Implicazione per il DES**: In Claude Code, gli hook DES sono configurati globalmente in `~/.claude/settings.json` e si applicano a tutti i progetti. In Kiro CLI, gli hook dovrebbero essere configurati per-workspace (in `.kiro/agents/` dentro la definizione agente) O per-workspace (in `.kiro/hooks/`). Non e possibile un'installazione globale "installa una volta, funziona ovunque" come in Claude Code.

**Fonte**: [Kiro CLI Settings](https://kiro.dev/docs/cli/reference/settings/) - Consultato 2026-03-07
**Confidenza**: High
**Verifica**: [Kiro CLI Steering](https://kiro.dev/docs/cli/steering/), [Kiro CLI Installation](https://kiro.dev/docs/cli/installation/), [GitHub Issue #5440](https://github.com/kirodotdev/Kiro/issues/5440)

---

### Finding 9: Sessioni e Stato

**Evidenza**: Il CLI di Kiro mantiene sessioni persistenti in un database SQLite locale [13].

**Dettagli sessione**:

| Caratteristica | Valore | Equivalente Claude Code |
|---------------|--------|------------------------|
| Storage | SQLite in `~/.kiro/` | Directory con file di sessione |
| Scope | Per-directory (ogni progetto ha sessioni separate) | Per-progetto |
| Identificatore | UUID (es. `f2946a26-3735-4b08-...`) | ID sessione opaco |
| Auto-save | Ogni turno di conversazione | Ogni turno |
| Resume | `--resume`, `--resume-picker`, `/chat resume` | `--resume` |
| Export | `/chat save <path>` (JSON) | Non esplicito |
| Import | `/chat load <path>` | Non esplicito |
| Delete | `--delete-session <UUID>` | Non esplicito |
| Cloud sync | NO | NO |

**Compaction**: Due modalita [14]:
- Manuale: `/compact`
- Automatica: al superamento del context window
- Configurabile: `compaction.excludeMessages` (default: 2), `compaction.excludeContextWindowPercent` (default: 2%)
- **Attenzione**: la compaction crea una NUOVA sessione; la sessione originale resta disponibile via `/chat resume`

**Session ID nel protocollo hook**: Il `session_id` NON e incluso nel JSON passato via STDIN agli hook. L'unico modo per identificare la sessione sarebbe interrogare il database SQLite o usare lo stato del filesystem [1][13].

**Fonte**: [Kiro CLI Session Management](https://kiro.dev/docs/cli/chat/session-management/) - Consultato 2026-03-07
**Confidenza**: High
**Verifica**: [Kiro CLI Context Management](https://kiro.dev/docs/cli/chat/context/), [Kiro CLI Commands](https://kiro.dev/docs/cli/reference/cli-commands/)

---

### Finding 10: Stop Hook vs SubagentStop -- La Semantica Diversa

**Evidenza**: Kiro CLI ha un hook `Stop` che "fires when assistant finishes responding (end of turn)" [1]. Kiro IDE ha un "Agent Stop" che "triggers when the agent has completed its turn, and finished responding to the user" [6]. Nessuno dei due e equivalente al `SubagentStop` di Claude Code.

**Confronto semantico**:

| Hook | Quando si attiva | Cosa riceve | Puo bloccare? |
|------|-----------------|-------------|---------------|
| Claude Code `SubagentStop` | Quando un sub-agente completa l'esecuzione | `tool_response` del sub-agente | No (post-hoc) |
| Claude Code `PostToolUse(Agent)` | Dopo che il tool Agent ha completato | `tool_response` | No (post-hoc) |
| Kiro CLI `Stop` | Fine del turno dell'agente PRINCIPALE | Solo `cwd` | No (post-hoc) |
| Kiro IDE `Agent Stop` | Fine del turno dell'agente PRINCIPALE | Non documentato | No (post-hoc) |

**Differenza critica**: In Claude Code, `SubagentStop` si attiva OGNI VOLTA che un sub-agente termina, permettendo al DES di validare l'output di ogni agente delegato. In Kiro, `Stop` si attiva solo alla fine del turno complessivo -- non per ogni sub-agente individualmente. Se l'agente principale lancia 3 sub-agenti in parallelo, il `Stop` si attiva UNA VOLTA alla fine, non 3 volte.

**PostToolUse su use_subagent**: Teoricamente, un hook `PostToolUse` con matcher `use_subagent` potrebbe attivarsi dopo che un sub-agente completa. Questo e il canale piu promettente per catturare il risultato di un sub-agente, ma la documentazione non conferma esplicitamente che `PostToolUse` riceva il `tool_response` completo del sub-agente [1][2].

**Fonte**: [Kiro CLI Hooks Documentation](https://kiro.dev/docs/cli/hooks/) - Consultato 2026-03-07
**Confidenza**: Medium (ipotesi su PostToolUse+use_subagent non verificata empiricamente)
**Verifica**: [Kiro Hook Types IDE](https://kiro.dev/docs/hooks/types/), [Kiro Hook Actions IDE](https://kiro.dev/docs/hooks/actions/)

---

### Finding 11: Agent Skills -- Il Sistema di Competenze

**Evidenza**: Kiro CLI supporta "Agent Skills" seguendo lo standard aperto agentskills.io. Ogni skill e una cartella con `SKILL.md` (YAML frontmatter + markdown body) e opzionalmente `references/` [15].

**Formato SKILL.md**:
```yaml
---
name: tdd-methodology
description: Guide for TDD development. Use when writing tests or implementing features with test-driven development.
---

# TDD Methodology
... istruzioni dettagliate ...
```

**Frontmatter obbligatorio**:

| Campo | Vincoli | Scopo |
|-------|---------|-------|
| `name` | Lowercase, numeri, trattini; max 64 char | Identificatore |
| `description` | Max 1024 char | Trigger di attivazione automatica |

**Caricamento**:
- Solo i metadati (name, description) caricati all'avvio
- Il contenuto completo caricato on-demand quando l'agente ne ha bisogno
- Default agent: carica automaticamente da `.kiro/skills/` e `~/.kiro/skills/`
- Custom agent: richiede registrazione esplicita via `resources: ["skill://.kiro/skills/*/SKILL.md"]`

**Confronto con nWave Skills**:

| Aspetto | nWave Skills | Kiro Agent Skills |
|---------|-------------|-------------------|
| Formato | YAML frontmatter + markdown | YAML frontmatter + markdown |
| Posizione | `~/.claude/skills/nw/{agent}/` | `~/.kiro/skills/{skill-name}/SKILL.md` |
| Caricamento | Imperativo (Read tool nel prompt agente) | Automatico (description-based matching) |
| Granularita | Per-agente, per-fase | Per-skill, keyword-based |
| Standard | Proprietario nWave | agentskills.io (aperto) |

**Implicazione**: Le skills nWave potrebbero essere portate su Kiro Skills con minimo effort (il formato e quasi identico). Il caricamento automatico basato su description e un vantaggio rispetto al caricamento imperativo di Claude Code.

**Fonte**: [Kiro CLI Agent Skills](https://kiro.dev/docs/cli/skills/) - Consultato 2026-03-07
**Confidenza**: High
**Verifica**: [Kiro CLI Creating Custom Agents](https://kiro.dev/docs/cli/custom-agents/creating/), [Kiro CLI Agent Configuration Reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/)

---

### Finding 12: Installazione, Piattaforme e Distribuzione

**Evidenza**: Il CLI e disponibile per macOS e Linux con vari metodi di installazione [16].

**Metodi di installazione**:

| Metodo | Piattaforma | Comando |
|--------|------------|---------|
| curl (script) | macOS, Linux | `curl -fsSL https://cli.kiro.dev/install \| bash` |
| Homebrew | macOS | `brew install kiro-cli` |
| AppImage | Linux (generico) | Download diretto |
| .deb | Ubuntu/Debian | `sudo dpkg -i kiro-cli.deb` |
| ZIP (x86_64) | Linux (glibc 2.34+) | Download diretto |
| ZIP (aarch64) | Linux ARM | Download diretto |
| ZIP musl | Linux (glibc < 2.34) | Download diretto |
| WSL | Windows (via WSL) | Installare in WSL, non nativo |

**NON disponibile**: npm, pip, Windows nativo.

**Requisiti**:
- glibc 2.34+ (o variante musl per sistemi piu vecchi)
- Architettura: x86_64 o aarch64
- Distribuzioni supportate: Fedora, Ubuntu, Amazon Linux 2023
- Autenticazione: obbligatoria (social login, Builder ID, o AWS IAM Identity Center)

**Headless/CI/CD**: Il CLI supporta `--no-interactive` per esecuzione non interattiva, ma l'autenticazione headless via SIGV4 e **BUGGY** -- il CLI v1.26.2 ignora `AMAZON_Q_SIGV4=true` e tenta OAuth via browser, che fallisce in ambienti senza GUI [19][20].

**Versioning**: Il CLI ha versioning indipendente dall'IDE. Attuale: CLI v1.27.1, IDE v0.9.x. Il CLI e piu maturo (v1.27) dell'IDE (v0.9) [22].

**Pricing e autenticazione**:
- Free: 50 crediti (perpetuo) + 500 bonus crediti primi 30 giorni
- Pro: $20/mese, 1000 crediti
- Pro+: $40/mese, 2000 crediti
- Power: $200/mese, 10000 crediti
- Overages: $0.04/credito aggiuntivo

**Fonte**: [Kiro CLI Installation](https://kiro.dev/docs/cli/installation/) - Consultato 2026-03-07
**Confidenza**: High
**Verifica**: [Kiro CLI Commands](https://kiro.dev/docs/cli/reference/cli-commands/), [Homebrew Formulae kiro-cli](https://formulae.brew.sh/cask/kiro-cli), [GitHub Issue #5938](https://github.com/kirodotdev/Kiro/issues/5938)

---

### Finding 13: Bug Noti e Limitazioni del Sistema Hook

**Evidenza**: L'analisi delle issue GitHub rivela diversi problemi rilevanti per il porting del DES [17][18][19][20][21].

**Bug e limitazioni documentati**:

| Issue | Descrizione | Stato | Impatto DES |
|-------|-------------|-------|-------------|
| [#5440](https://github.com/kirodotdev/Kiro/issues/5440) | Hook globali (`~/.kiro/hooks/`) non supportati | **Aperta**, 15 thumbs up, nessuna risposta team | ALTO -- impedisce installazione globale |
| [#5372](https://github.com/kirodotdev/Kiro/issues/5372) | agentSpawn hook: risposte agente non visualizzate nel terminale | Riaperta dopo review | MEDIO -- SessionStart equivalente non affidabile |
| [#4889](https://github.com/kirodotdev/Kiro/issues/4889) | Hook bypassa context auto-summary, causa crash per overflow contesto | Aperta, pending maintainer | ALTO -- hook pesanti (come DES) rischiano overflow |
| [#1953](https://github.com/kirodotdev/Kiro/issues/1953) | Hook lenti (piu lenti dell'esecuzione manuale dei comandi) | Aperta, riclassificata da Bug a Feature | MEDIO -- DES genera 5-15 hook/ciclo |
| [#5938](https://github.com/kirodotdev/Kiro/issues/5938) | Autenticazione SIGV4 headless non funziona (CLI ignora env var) | Aperta, pending triage | BASSO -- impatta solo CI/CD |
| [#1559](https://github.com/kirodotdev/Kiro/issues/1559) | Hook non acceduti o non pushati al contesto nelle azioni appropriate | Aperta | MEDIO -- potenziale perdita di contesto DES |

**Confronto con bug di Claude Code**:

| Problematica | Claude Code | Kiro CLI |
|-------------|-------------|----------|
| SubagentStart non affidabile | 42% failure rate (#27755) | AgentSpawn con bug display (#5372) |
| Hook lenti | Non documentato come problema | Documentato (#1953) |
| Context overflow con hook | Non documentato | Documentato (#4889) |
| Hook globali | Supportati (settings.json) | NON supportati (#5440) |

**Fonte**: [GitHub kirodotdev/Kiro Issues](https://github.com/kirodotdev/Kiro) - Consultato 2026-03-07
**Confidenza**: High
**Verifica**: Analisi diretta di 6 issue GitHub

---

### Finding 14: Differenze Critiche con Claude Code -- Tabella Riassuntiva

**Evidenza**: Sintesi comparativa basata su tutti i finding precedenti.

| Caratteristica | Claude Code | Kiro CLI | Impatto Porting |
|---------------|-------------|----------|----------------|
| **Hook nei sub-agent** | SI | NO | BLOCCANTE |
| **SubagentStop** | SI | NO (solo Stop generico) | BLOCCANTE |
| **SubagentStart** | SI (buggy, 42% failure) | NO | ALTO |
| **SessionStart** | SI | AgentSpawn (equivalente) | COMPATIBILE |
| **PreToolUse blocco** | Exit 2 + JSON stdout | Exit 2 + STDERR | COMPATIBILE |
| **PostToolUse** | SI | SI | COMPATIBILE |
| **JSON protocol** | Via STDIN, session_id presente | Via STDIN, session_id ASSENTE | ADATTABILE |
| **Hook globali** | SI (settings.json) | NO (solo per-workspace/per-agente) | ALTO |
| **Tool Edit separato** | SI | NO (tutto via write) | ADATTABILE |
| **maxTurns** | SI (frontmatter) | NO | ALTO |
| **Formato agente** | YAML frontmatter + markdown | JSON | ADATTABILE |
| **Skills** | Proprietario nWave | agentskills.io standard | COMPATIBILE |
| **Steering** | CLAUDE.md | .kiro/steering/ | COMPATIBILE |
| **MCP** | Supportato | Supportato nativamente | COMPATIBILE |
| **Modelli AI** | Claude (tutti) | Claude (tutti) | IDENTICO |

**Confidenza**: High
**Verifica**: Tutti i finding 1-13

---

## Source Analysis

| # | Fonte | Dominio | Reputazione | Tipo | Data Accesso | Cross-verificata |
|---|-------|---------|-------------|------|-------------|-----------------|
| 1 | Kiro CLI Hooks Docs | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 2 | Kiro CLI Built-in Tools | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 3 | Kiro CLI Creating Custom Agents | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 4 | Kiro CLI Agent Config Reference | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 5 | Kiro CLI Agent Examples | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 6 | Kiro Hook Types IDE | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 7 | Kiro Subagents IDE | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 8 | Kiro CLI Subagents | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 9 | Kiro Changelog IDE v0.8-0.9 | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 10 | Kiro CLI Steering | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 11 | Kiro CLI Settings | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 12 | Kiro CLI Experimental Features | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 13 | Kiro CLI Session Management | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 14 | Kiro CLI Context Management | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 15 | Kiro CLI Agent Skills | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 16 | Kiro CLI Installation | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 17 | GitHub Issue #5440 | github.com | Medium-High (0.8) | Community | 2026-03-07 | Si |
| 18 | GitHub Issue #4889 | github.com | Medium-High (0.8) | Community | 2026-03-07 | Si |
| 19 | GitHub Issue #5938 | github.com | Medium-High (0.8) | Community | 2026-03-07 | Si |
| 20 | GitHub Issue #5372 | github.com | Medium-High (0.8) | Community | 2026-03-07 | Si |
| 21 | GitHub Issue #1953 | github.com | Medium-High (0.8) | Community | 2026-03-07 | Si |
| 22 | Kiro CLI Changelog | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 23 | Kiro CLI Commands Reference | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 24 | Kiro Hook Actions IDE | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 25 | Kiro Pricing | kiro.dev | High (1.0) | Ufficiale | 2026-03-07 | Si |
| 26 | Tembo CLI Comparison | tembo.io | Medium-High (0.8) | Industria | 2026-03-07 | Si |
| 27 | MorphLLM Kiro vs Claude Code | morphllm.com | Medium (0.6) | Industria | 2026-03-07 | Si |
| 28 | GitHub Marketplace setup-kiro-action | github.com | Medium-High (0.8) | Community | 2026-03-07 | Si |

Reputazione: High: 20 (71%) | Medium-High: 7 (25%) | Medium: 1 (4%) | Avg: 0.93

---

## Knowledge Gaps

### Gap 1: Hook nei Sub-Agent del CLI -- Conferma Esplicita Mancante

**Problema**: La documentazione IDE afferma esplicitamente "Hooks will not trigger in subagents" [7]. La documentazione CLI dei sub-agent NON contiene questa affermazione esplicita [8]. Non e possibile confermare al 100% che il comportamento sia identico nel CLI, anche se e altamente probabile.
**Tentato**: Documentazione CLI sub-agent, changelog CLI, changelog IDE, 3 ricerche web mirate
**Raccomandazione**: Test empirico: creare un agente con un PreToolUse hook e lanciarlo come sub-agente, verificando se l'hook si attiva.

### Gap 2: PostToolUse su use_subagent -- Tool Response

**Problema**: Non e documentato se un hook `PostToolUse` con matcher `use_subagent` riceva il `tool_response` completo del sub-agente o solo un summary. Questo e il canale piu promettente per un "SubagentStop" surrogato.
**Tentato**: Documentazione hooks CLI, examples, changelog
**Raccomandazione**: Test empirico: creare un PostToolUse hook con matcher `use_subagent` e loggare il JSON ricevuto via STDIN.

### Gap 3: Modifica tool_input da Hook

**Problema**: Non e documentato se un PreToolUse hook possa modificare il `tool_input` restituendo JSON modificato su STDOUT con exit code 0. La documentazione dice solo che STDOUT e "captured" ma non specifica se viene usato per sovrascrivere i parametri.
**Tentato**: Documentazione hooks CLI, ricerche web, issue GitHub
**Raccomandazione**: Test empirico o feature request su GitHub.

### Gap 4: session_id o Identificatore di Sessione negli Hook

**Problema**: Il JSON degli hook non contiene `session_id`. Non e chiaro se esista un meccanismo alternativo (env var, file) per identificare la sessione corrente dall'interno di un hook.
**Tentato**: Documentazione hooks, settings, session management, environment variables
**Raccomandazione**: Usare il database SQLite (`~/.kiro/`) per interrogare la sessione corrente, o derivare un ID dalla combinazione CWD + timestamp.

### Gap 5: maxTurns o Limite di Turni

**Problema**: Non esiste un campo `maxTurns` nella configurazione agente del CLI. Non e documentato alcun meccanismo per limitare il numero di turni di un agente o sub-agente.
**Tentato**: Agent configuration reference, examples, settings, changelog
**Raccomandazione**: Implementare un turn counter esterno via hook (AgentSpawn per inizializzare, PostToolUse per incrementare, PreToolUse per bloccare al limite).

### Gap 6: Sub-agent Nested (Ricorsivi)

**Problema**: Non e documentato se un sub-agente possa invocare `use_subagent` per creare sub-agenti nested. In Claude Code, nWave usa solo un livello di delegazione, ma la possibilita di nesting potrebbe aprire pattern alternativi.
**Tentato**: Documentazione sub-agent CLI e IDE, tool list sub-agent
**Raccomandazione**: Test empirico.

### Gap 7: Environment Variables Passate agli Hook

**Problema**: L'IDE documenta `USER_PROMPT` come env var per gli hook di tipo Prompt Submit. Il CLI non documenta esplicitamente quali env var sono disponibili negli hook (oltre a quelle del sistema).
**Tentato**: Documentazione hooks CLI e IDE, ricerche web
**Raccomandazione**: Test empirico con `env` come comando hook per elencare tutte le variabili.

---

## Conflicting Information

### Conflitto 1: Nomi Tool nel Protocollo Hook

**Posizione A**: La documentazione hook CLI elenca nomi canonici come `fs_read`, `fs_write`, `execute_bash` per i matcher [1].
**Posizione B**: La documentazione built-in tools elenca i tool con nomi semplici: `read`, `write`, `shell` [2]. Gli esempi di hook usano gli alias (es. `"matcher": "write"`, non `"matcher": "fs_write"`).
**Valutazione**: Entrambi i formati sono accettati come matcher. Il `tool_name` nel JSON dell'evento hook probabilmente usa il nome canonico internamente, ma il matcher accetta sia canonici che alias. Risoluzione: usare alias nei matcher per coerenza con la documentazione examples.

### Conflitto 2: Kiro CLI Maturity vs IDE

**Posizione A**: Il CLI e a v1.27.1, suggerendo maturita [22].
**Posizione B**: L'IDE e a v0.9.x, suggerendo pre-release [9]. Tuttavia, il CLI condivide la stessa architettura e potrebbe avere le stesse limitazioni.
**Valutazione**: Il CLI e un prodotto separato con versioning indipendente. La maggiore maturita (v1.27 vs v0.9) indica piu iterazioni e stabilita, ma non necessariamente feature-completeness nel dominio hook/sub-agent.

---

## Analisi Tecnica: Porting DES -- Dettaglio per Componente

### Componente 1: claude_code_hook_adapter.py

**Stato attuale**: Riceve JSON da Claude Code hooks via STDIN, lo parsa, e lo despacha a PreToolUseService, PostToolUseService, SubagentStopService in base all'evento.

**Porting su Kiro CLI**:
- **Fattibile**: Il formato JSON e simile. Il dispatch cambierebbe i nomi degli eventi (`preToolUse` vs `PreToolUse` nel tipo, ma la struttura e analoga).
- **Modifiche necessarie**:
  1. Mappare `hook_event_name` Kiro ai servizi DES
  2. Mappare `tool_name` Kiro ai tool name DES (`write` -> `Write`, `use_subagent` -> `Agent`)
  3. Gestire l'assenza di `session_id` (generare un ID basato su CWD + timestamp)
  4. Rimuovere la gestione di SubagentStop (non esiste in Kiro)
  5. Collassare Write/Edit in un unico handler (Kiro non distingue)
- **Effort stimato**: 3-5 giorni

### Componente 2: PreToolUseService

**Stato attuale**: Valida che l'agente rispetti la fase TDD, che i file modificati siano coerenti con la fase, che il template DES abbia le 9 sezioni.

**Porting su Kiro CLI**:
- **Parzialmente fattibile**: Le validazioni funzionano sull'agente principale. Non funzionano sui sub-agenti.
- **Modifiche necessarie**:
  1. Adattare i tool name (`write` invece di `Write`/`Edit`)
  2. Restituire exit code 2 per blocco (gia compatibile)
  3. Restituire la reason via STDERR (invece di JSON su STDOUT)
- **Limitazione**: La validazione non si attiva dentro i sub-agent, quindi il ciclo TDD a 5 fasi non e enforceable quando il lavoro e delegato.
- **Effort stimato**: 2-3 giorni

### Componente 3: SubagentStopService

**Stato attuale**: Valida l'output del sub-agente, determina se il ciclo e completo.

**Porting su Kiro CLI**:
- **NON fattibile** con il modello attuale. Non esiste un equivalente di SubagentStop.
- **Workaround possibile**: Usare un `PostToolUse` con matcher `use_subagent` per catturare il risultato del sub-agente. Richiede verifica empirica (Gap 2).
- **Effort stimato**: Sconosciuto (dipende dalla verifica empirica)

### Componente 4: Orchestrator (fase rendering, turn counter)

**Stato attuale**: Gestisce il rendering dei prompt per fase, il conteggio turni, il timeout.

**Porting su Kiro CLI**:
- **Parzialmente fattibile**: Il rendering prompt puo funzionare via steering files. Il turn counter puo essere implementato via file di stato (scritto da AgentSpawn, incrementato da PostToolUse). Il timeout puo essere gestito dal timeout_ms degli hook.
- **Limitazione**: Senza `maxTurns`, il turn counter puo solo loggare, non bloccare (a meno di non usare PreToolUse exit 2 quando il contatore supera il limite).
- **Effort stimato**: 5-7 giorni

### Componente 5: TemplateValidator

**Stato attuale**: Verifica che i prompt degli agenti contengano le 9 sezioni DES obbligatorie.

**Porting su Kiro CLI**:
- **Fattibile con adattamento**: Il prompt dell'agente e nel campo `prompt` del JSON (o in un file referenziato via `file://`). La validazione puo essere eseguita dall'hook AgentSpawn.
- **Effort stimato**: 1-2 giorni

### Effort Totale Stimato per PoC (solo agente principale, senza sub-agent enforcement)

| Componente | Effort | Fattibilita |
|-----------|--------|-------------|
| Hook Adapter | 3-5 giorni | Alta |
| PreToolUseService | 2-3 giorni | Alta (solo agente principale) |
| SubagentStopService | N/A | Non fattibile |
| Orchestrator (parziale) | 5-7 giorni | Media |
| TemplateValidator | 1-2 giorni | Alta |
| Test e integrazione | 3-5 giorni | Media |
| **Totale** | **14-22 giorni** | **Medio** |

---

## Recommendations for Further Research

1. **Test empirico PostToolUse+use_subagent**: Verificare se un hook PostToolUse con matcher `use_subagent` riceve il `tool_response` completo del sub-agente. Se si, questo e il canale per un SubagentStop surrogato.

2. **Test empirico hook nei sub-agent CLI**: Verificare empiricamente che gli hook NON si attivano nei sub-agent del CLI, dato che la documentazione CLI non lo afferma esplicitamente (solo l'IDE lo fa).

3. **Feature request su GitHub**: Aprire una issue su kirodotdev/Kiro per richiedere:
   - Hook attivi nei sub-agent (caso d'uso: framework di enforcement TDD)
   - Hook globali (`~/.kiro/hooks/`) -- rafforzare la #5440 con il caso d'uso nWave
   - Campo `maxTurns` nella configurazione agente
   - `session_id` nel protocollo JSON degli hook

4. **PoC MCP Server DES**: Anziche portare il DES come hook, considerare l'alternativa di esporlo come server MCP. Un MCP server DES sarebbe invocabile sia da Claude Code che da Kiro, e non dipenderebbe dal modello hook della piattaforma.

5. **Monitoraggio evolutivo**: La v1.23 ha introdotto sub-agent (dicembre 2025). La feature e molto recente. E plausibile che hook nei sub-agent vengano aggiunti in versioni future. Monitorare il changelog.

6. **Benchmark performance hook**: Testare il DES con i carichi tipici di nWave (5-15 hook/ciclo) su Kiro CLI per verificare la latenza. La Issue #1953 suggerisce che gli hook possano essere lenti.

---

## Full Citations

[1] Amazon/Kiro. "Hooks - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/hooks/. Accessed 2026-03-07.
[2] Amazon/Kiro. "Built-in tools - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/reference/built-in-tools/. Accessed 2026-03-07.
[3] Amazon/Kiro. "Creating custom agents - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/custom-agents/creating/. Accessed 2026-03-07.
[4] Amazon/Kiro. "Agent configuration reference - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/custom-agents/configuration-reference/. Accessed 2026-03-07.
[5] Amazon/Kiro. "Agent Examples - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/custom-agents/examples/. Accessed 2026-03-07.
[6] Amazon/Kiro. "Hook types - IDE - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/hooks/types/. Accessed 2026-03-07.
[7] Amazon/Kiro. "Subagents - IDE - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/chat/subagents/. Accessed 2026-03-07.
[8] Amazon/Kiro. "Subagents - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/chat/subagents/. Accessed 2026-03-07.
[9] Amazon/Kiro. "IDE Changelog". kiro.dev. 2025-2026. https://kiro.dev/changelog/ide/. Accessed 2026-03-07.
[10] Amazon/Kiro. "Steering - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/steering/. Accessed 2026-03-07.
[11] Amazon/Kiro. "Settings - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/reference/settings/. Accessed 2026-03-07.
[12] Amazon/Kiro. "Experimental features - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/experimental/. Accessed 2026-03-07.
[13] Amazon/Kiro. "Session management - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/chat/session-management/. Accessed 2026-03-07.
[14] Amazon/Kiro. "Context management - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/chat/context/. Accessed 2026-03-07.
[15] Amazon/Kiro. "Agent Skills - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/skills/. Accessed 2026-03-07.
[16] Amazon/Kiro. "Installation - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/installation/. Accessed 2026-03-07.
[17] msayed-treezor. "Support for Global Hooks (~/.kiro/hooks/) - Issue #5440". GitHub kirodotdev/Kiro. 2026-02-05. https://github.com/kirodotdev/Kiro/issues/5440. Accessed 2026-03-07.
[18] chinlung. "Hook execution bypasses context auto summary - Issue #4889". GitHub kirodotdev/Kiro. 2025. https://github.com/kirodotdev/Kiro/issues/4889. Accessed 2026-03-07.
[19] "Feature: Headless/SIGV4 authentication for kiro-cli-chat - Issue #5938". GitHub kirodotdev/Kiro. 2026-02-22. https://github.com/kirodotdev/Kiro/issues/5938. Accessed 2026-03-07.
[20] "kiro-cli Bug: Agent Responses Not Displayed with agentSpawn Hooks - Issue #5372". GitHub kirodotdev/Kiro. 2026-02-02. https://github.com/kirodotdev/Kiro/issues/5372. Accessed 2026-03-07.
[21] omkarok. "Agent hooks are slow - Issue #1953". GitHub kirodotdev/Kiro. 2025. https://github.com/kirodotdev/Kiro/issues/1953. Accessed 2026-03-07.
[22] Amazon/Kiro. "CLI Changelog". kiro.dev. 2025-2026. https://kiro.dev/changelog/cli/. Accessed 2026-03-07.
[23] Amazon/Kiro. "CLI commands - CLI - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/cli/reference/cli-commands/. Accessed 2026-03-07.
[24] Amazon/Kiro. "Hook actions - IDE - Docs". kiro.dev. 2025-2026. https://kiro.dev/docs/hooks/actions/. Accessed 2026-03-07.
[25] Amazon/Kiro. "Pricing". kiro.dev. 2025-2026. https://kiro.dev/pricing/. Accessed 2026-03-07.
[26] Tembo. "The 2026 Guide to Coding CLI Tools: 15 AI Agents Compared". tembo.io. 2026. https://www.tembo.io/blog/coding-cli-tools-comparison. Accessed 2026-03-07.
[27] MorphLLM. "Kiro vs Claude Code 2026". morphllm.com. 2026. https://www.morphllm.com/comparisons/kiro-vs-claude-code. Accessed 2026-03-07.
[28] clouatre-labs. "Setup Kiro CLI - GitHub Marketplace". github.com. 2026. https://github.com/marketplace/actions/setup-kiro-cli. Accessed 2026-03-07.

---

## Research Metadata

Durata: ~40 min | Esaminate: 35+ pagine | Citate: 28 | Cross-ref: 28 | Confidenza: High 86%, Medium 14%, Low 0% | Output: docs/research/kiro-cli-deep-dive-research.md
