[BUG] Kiro hook integrator emits the legacy pre-1.0 hook schema

[TibRib]

Describe the bug

apm install deploys hooks to the kiro target in the deprecated pre-1.0 Kiro hook schema
({ "when": {...}, "then": { "type": "runCommand" } }).

Kiro IDE 1.0 / CLI v3 replaced that schema with a versioned, standalone format:

{
  "version": "v1",
  "hooks": [
    { "name": "...", "trigger": "PreToolUse", "matcher": "...", "action": { "type": "command", "command": "..." } }
  ]
}

(See Kiro CLI v3 hooks and the
Kiro IDE 1.0 changelog.)

As a result, hooks that APM deploys to .kiro/hooks/ are treated by Kiro 1.0 as legacy
(migrate-only via the Agent Hooks panel), not as the current runtime format. On top of the
format mismatch there are three functional gaps (details below): no agent (prompt) action,
matcher/trigger naming differences, and several 1.0 triggers that don't map at all.

Context: the Kiro target was added relatively recently (#702, milestone 0.20.0), which predates
Kiro's 1.0 hook-schema change — so the integrator was written against the older shape.

To Reproduce

1. Create a minimal package:

   apm.yml

   name: hook-repro
   version: 0.0.1
   targets: [kiro, claude, copilot]
   includes: auto

   .apm/instructions/dummy.instructions.md

   ---
   description: dummy
   applyTo: "**/*.md"
   ---
   - placeholder

   .apm/hooks/check.json (documented Claude shape, type: command)

   {
     "hooks": {
       "PreToolUse": [
         { "matcher": "fs_write|str_replace",
           "hooks": [ { "type": "command", "command": "echo pre-write-check", "timeout": 10 } ] }
       ]
     }
   }

2. Run apm install.

3. Inspect .kiro/hooks/hook-repro-check-pretooluse-1.json.

Actual output (APM 0.24.0)

{
  "name": "hook-repro preToolUse 1",
  "version": "1.0.0",
  "when": {
    "type": "preToolUse",
    "patterns": ["fs_write|str_replace"]
  },
  "then": {
    "type": "runCommand",
    "command": "echo pre-write-check"
  }
}

This is the pre-1.0 schema (when/then/runCommand, camelCase when.type, patterns).

Expected behavior
(Kiro 1.0 / v3 schema)

{
  "version": "v1",
  "hooks": [
    {
      "name": "hook-repro pre-write-check",
      "trigger": "PreToolUse",
      "matcher": "fs_write|str_replace",
      "action": { "type": "command", "command": "echo pre-write-check", "timeout": 10 }
    }
  ]
}

Differences: top-level version: "v1" + a hooks array; trigger (PascalCase) instead of
when.type (camelCase); matcher instead of patterns; action instead of then; and
action.type: "command" instead of then.type: "runCommand".

Additional gaps found while testing

Beyond the format, three things block real usage on Kiro 1.0:

1. No agent action. APM only maps type: command -> runCommand. Kiro 1.0 supports
   action.type: "agent" (append a prompt to the model context, no subprocess), which is the
   right primitive for lightweight steering/guardrails. There is no way to author or emit an
   agent-action hook through APM today.

2. Trigger mapping is stale / partial. Observed mappings on the kiro target:

   Authored (Claude shape)	APM emits (when.type)	Kiro 1.0 expects (trigger)
   PreToolUse	preToolUse (+ patterns)	PreToolUse (+ matcher)
   PostToolUse	postToolUse (+ patterns)	PostToolUse (+ matcher)
   Stop	agentStop	Stop
   UserPromptSubmit	promptSubmit	UserPromptSubmit
   SessionStart	(passed through, casing-mismatch warning)	SessionStart
   SubagentStop	(passed through, warning)	(n/a — use Stop)
   PreCompact	(passed through, warning)	(n/a)

   Kiro 1.0 also adds triggers with no APM path: PreTaskExec, PostTaskExec,
   PostFileCreate, PostFileSave, PostFileDelete.

3. Native v1 files are rejected, so authors can't work around the above by shipping the
   correct format directly. A .apm/hooks/*.json in the v1 shape fails install with:

   WARNING apm_cli.integration.hook_integrator Skipping malformed hook file ...: 'hooks' must be a dict, got list
   

   (Kiro 1.0's hooks is an array; APM's validator requires an object.)

Impact

Packages that target kiro cannot ship hooks that run on Kiro 1.0 without a manual migration
step per consumer. The only clean cross-target workaround today is to express hook intent as
instructions (which compile correctly to .kiro/steering/), but that loses the
command/exit-code enforcement and event-fired triggering that hooks provide — and it can't
represent a genuine blocking validation gate (e.g. a pre-task branch/worktree check).

Suggested fix / acceptance criteria

• Emit the Kiro 1.0 v1 schema for the kiro target: { "version": "v1", "hooks": [ { "name", "trigger", "matcher", "action": { "type", "command"|"prompt", "timeout"? } } ] }.
• Map events to Kiro 1.0 PascalCase trigger names and use matcher (not patterns).
• Support an agent/prompt action for Kiro (either a first-class portable action or a
  documented Kiro-scoped passthrough), so prompt-based guardrails can be deployed rather than
  only shell commands.
• Optionally: accept native Kiro v1 hook files in .apm/hooks/ (array-shaped hooks) so
  authors can target Kiro directly when a portable expression isn't possible.

Environment

• APM version: 0.24.0 (latest at time of writing; also reproduced against the 0.24.0
  release notes, which include hook fixes [BUG] Copilot hook events are never renamed to camelCase #1977 / [BUG] Combined hook manifests (claude-codex-hooks.json) route to one target only; claude silently gets Copilot-schema fallback hooks #2020 / [BUG] Deployed hook scripts crash at runtime: required sibling modules are not copied, and the consumer's package.json module type is applied to them #2023 but no Kiro-1.0 schema update).
• OS: Windows 11.
• Kiro: IDE 1.0 / CLI v3 hook schema.

References

• APM Kiro target support: [FEATURE] Kiro Support #702 (milestone 0.20.0).
• Kiro CLI v3 hooks: https://kiro.dev/docs/cli/v3/hooks/
• Kiro IDE 1.0 changelog (hooks section + "manual hooks replaced by manual steering files"):
  https://kiro.dev/changelog/ide/1-0/

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/distribution
type/bug
status/accepted

Milestone

null

Suggested next action

Update KiroHookIntegrator to emit the Kiro v1 schema ({ "version": "v1", "hooks": [...] }) with PascalCase trigger, matcher, and action fields; update the hook file validator to accept array-shaped hooks for native v1 passthrough; and open a follow-up issue for the agent action type design.

Suggested issue comment

Thanks for the comprehensive report, TibRib -- the side-by-side schema comparison, the trigger mapping table, and the three functional gap sections make this immediately actionable.

This is a confirmed bug. The `kiro` integrator was written against the pre-1.0 hook schema (`when`/`then`/`runCommand`) before Kiro 1.0 shipped its versioned format. The fix has four parts:

**1. Schema migration (primary bug fix):**
Emit `{ "version": "v1", "hooks": [ { "name", "trigger" (PascalCase), "matcher", "action": { "type": "command", "command", "timeout" } } ] }` for all `kiro` target hook files.

**2. Trigger mapping update:**
Use your mapping table as the reference: `preToolUse` -> `PreToolUse` (+ `matcher` not `patterns`), `agentStop` -> `Stop`, `promptSubmit` -> `UserPromptSubmit`. New Kiro 1.0 triggers (`PreTaskExec`, `PostTaskExec`, `PostFileCreate`, `PostFileSave`, `PostFileDelete`) can be surfaced as passthrough with a warning for now.

**3. Native v1 passthrough:**
Update the hook file validator to accept array-shaped `hooks` (the Kiro v1 shape). The current rejection ("'hooks' must be a dict, got list") blocks authors from shipping Kiro-native format directly.

**4. Agent action type (follow-up, not in scope for the initial fix):**
The `agent`/prompt action is a new primitive concept with no direct portable equivalent in the current Claude hook shape. Please open a follow-up issue to design the authoring format for prompt-based guardrails -- that design decision is non-trivial and should not block the schema migration above.

The integrator lives in `src/apm_cli/integration/hook_integrator.py`. The trigger mapping and schema change are bounded and testable. If you want to contribute, the fix for parts 1-3 is a clean, self-contained PR.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

APM deploys hooks that Kiro 1.0 treats as legacy without any warning to the user -- this is a silent correctness failure. The user has no indication from APM that their hook will be flagged as "legacy" in Kiro's Agent Hooks panel and will require manual migration. The fix restores the expected UX: apm install -> hook works on Kiro 1.0. The validator rejection of native v1 files adds a secondary pain point: authors who know the correct format cannot work around the integrator bug.

Supply Chain Security Expert -- Risk-Surface Reviewer

Hook deployment to .kiro/hooks/ is a file-integration surface. The schema change affects field names and structure, not the security model. The cleanup.py safety gates and path_security guards are not affected. No path traversal or auth implications. No theme/security or theme/governance required.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author is a first-time contributor (author_association: NONE) who tested against Kiro 1.0 IDE, referenced the IDE changelog and CLI v3 docs, and identified four distinct gaps. This level of investigation deserves explicit acknowledgment. The reply splits the fix into four numbered parts so the scope is clear, and explicitly requests a follow-up issue for the agent action so the PR doesn't grow unbounded. Point directly to the integrator file.

Python Architect -- Architecture Reviewer

Activated -- the schema migration changes the integrator's output contract (the shape of every file it writes to .kiro/hooks/). The KiroHookIntegrator needs to update its schema emission, trigger mapping table, and accept native v1 input format in the validator. These are bounded changes within the integrator class, but they constitute a schema version bump that may need a version guard if the integrator needs to support both old and new consumers. The agent action type is correctly split off: it requires designing a new portable authoring primitive (does APM's hook format gain a type: agent action? does it require a new top-level concept?), which is a cross-cutting decision that deserves its own issue and design doc.

Doc Writer -- Documentation Reviewer

Activated -- the Kiro integration guide needs to document the v1 schema APM emits, the supported trigger names in PascalCase, and the native v1 passthrough option once it works. The implementing PR must update the relevant docs. The suggested comment splits the fix clearly so the implementing PR scope is unambiguous.

APM CEO -- Triage Arbiter

Portability is a mega-theme, and Kiro 1.0 is a shipping IDE. APM's Kiro hooks being treated as "legacy" by default is a portability regression that reflects poorly on APM's multi-tool deployment story. The schema migration is non-controversial and urgent -- every Kiro 1.0 user is affected. The agent action gap is real but architecturally non-trivial (new primitive type). The correct call is to accept the schema migration immediately and spin off the agent design as a separate tracked issue. Accept with theme/portability and area/distribution.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/distribution"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Update KiroHookIntegrator to emit the Kiro v1 schema with PascalCase triggers and action fields; update the validator to accept array-shaped hooks; open a follow-up issue for the agent action type design.",
  "comment_markdown": "This is a confirmed bug. The kiro integrator emits the pre-1.0 schema. The fix has four parts: schema migration to v1 format, trigger mapping update, native v1 passthrough acceptance in the validator, and a follow-up issue for the agent action type."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · 167.5 AIC · ⌖ 15.8 AIC · ⊞ 9.2K · ◷