Kiro Hooks

Hooks live under upstream .kiro/hooks/*.kiro.hook using the IDE schema (enabled / when / then). Do not use the CLI 3.0 version: v1 + hooks[] wrapper — the Agent Hooks panel will not list those files.

File	when.type	Behavior
pr-readiness-coach.kiro.hook	fileEdited (*.ts / *.tsx / *.js / *.mjs)	Heuristic-only npm run hook, 30s
pr-readiness-full.kiro.hook	userTriggered	Full Bedrock (PR_READY_HOOK_LOCAL=0), 120s — use play in Agent Hooks
build-on-stop.kiro.hook	agentStop	npm run build after agent turn
test-after-task.kiro.hook	postTaskExecution	npm test after a spec task completes

src/hook/kiro-hook.ts always exits 0 (warn-only). It prints a human report; if the verdict is not READY, it reminds that analysis is warn-only. On timeout or error it prints “Analysis skipped; push proceeding” and still exits 0.

Why this shape

Local feedback on save (and on demand) without blocking merges; reuses the core module shared with CLI and Lambda. Full Bedrock stays on the slower userTriggered / CLI path so save stays under 30s — the full pipeline often exceeds that budget.

Environment

Variable	Role
PR_READY_HOOK_LOCAL unset or not 0	Default save path — local heuristics only
PR_READY_HOOK_LOCAL=0	Full Bedrock profile
PR_READY_HOOK_TIMEOUT_MS=120000	Timeout for the full profile (120s)
AWS_PROFILE / AWS_REGION	Required for full mode; must be visible to the Kiro process

Hook runtime uses local tsx (project engines / Lambda use Node.js 24.x).

CLI equivalents

# Same as fileEdited default
npm run hook

# Same as userTriggered full profile (needs Bedrock credentials)
export AWS_PROFILE=<your-profile>
export AWS_REGION=<your-region>
aws sso login --profile "$AWS_PROFILE"
PR_READY_HOOK_LOCAL=0 PR_READY_HOOK_TIMEOUT_MS=120000 npm run hook

Caution

Kiro’s Agent Hooks runner often does not inherit env from a separate terminal. If the Full hook reports Could not load credentials from any providers, launch Kiro from a shell that already has AWS_PROFILE / AWS_REGION set after aws sso login — do not commit personal profile names into .kiro.hook files.

Pitfalls

• Keep fileEdited on heuristics — full Bedrock on save will miss the 30s ceiling
• Hook must never hard-fail the editor workflow (always exit 0)
• Do not claim Kiro runs inside GitHub Actions
• CLI 3.0 hook JSON (trigger / action / hooks[]) is invisible in the IDE Agent Hooks panel
• testPathAllowlist in ready.yml keeps fixture secrets under tests/** from failing the hook

Tip

Reload the Kiro window if panel entries are stale after hook file edits.

Demo evidence

Agent Hooks panel — Run Command Hook / PR Readiness Coach (Full):

Full-mode hook run (PR_READY_HOOK_LOCAL=0) returning READY with draft PR title/body: