Kiro CLI agent status: a cookbook recipe

[bitcldr]

Following up on #332, same question for a different agent: kiro-cli reports nothing to the sidebar right now, and I don't think it can be wired up the way Claude Code, Codex, Pi, and OpenCode are.

Two things stop a hook-based integration, both checked against the actual binary (kiro-cli 2.16.1) rather than its docs, which describe a format this version doesn't implement:

• Kiro declares hooks per agent, inside each ~/.kiro/agents/<name>.json. There's no global file. A merge would cover one agent and get overwritten by whatever else manages the rest - I have 66 of them on this machine, most rewritten by other tooling. kiro-cli agent validate rejects unknown event names, which makes it a decent oracle: only five events exist (agentSpawn, userPromptSubmit, preToolUse, postToolUse, stop), nothing permission-shaped.
• preToolUse fires with the same payload whether the tool was auto-approved or is actually waiting on you. Wiring it to blocked would light up amber on every trusted tool call.

So instead of a hook I wrote a cookbook recipe that reads the pane. It starts a small poller from the shell (preexec/precmd, zsh/bash/fish all covered) when a kiro/kiro-cli command runs, and the poller calls the stock agterm-agent-status.sh - same script Kimi's recipe points at - with active while kiro's footer says it's working, blocked while its approval dialog is actually on screen, completed when the turn ends. The approval-detection strings are a transcript of a real dialog, not a guess:

 shell requires approval
 ❯ Yes, single permission
   Trust, always allow in this session
   No (Tab to edit)
 esc to close · ↑↓ to navigate

blocked requires the anchor line plus one of the option rows together - the anchor alone is just English and turns up in a grep hit or a policy doc.

I went cookbook rather than the installer on purpose. Kimi's recipe is a config snippet because kimi's own hooks already do the disambiguation; this one is closer to what the Codex adapter does (reading the pane as the actual signal, not a correction to one), and that felt like more machinery than I wanted to hand you unasked. Happy to be told otherwise if you'd rather this land in the installer - I don't have strong feelings on which, just wanted to check before opening a PR either way.

Tested it live: kiro-cli chat reports active/blocked/completed correctly. One real gap the pane-reading has, worth flagging up front - it's only as good as your shell's preexec hook actually seeing the literal command you typed. An alias with a different name (I have one) needs its name added to the regex, or it's silently never detected. Documented in the recipe's Limits section, but it's the kind of thing that bites quietly.

If this approach makes sense to you, I'd like to move forward and open a PR against cookbook/.

[umputun]

cookbook, and your read on the hook route matches mine. Send the PR against cookbook/.

one thing worth knowing before you write it. The hooks package already installs a generic shell integration, shell/integration.sh and integration.fish, which does the preexec/precmd match against an overridable regex:

export AGTERM_AGENT_RE='^(gemini|cursor-agent|aider|crush|goose|kiro|kiro-cli)([[:space:]]|$)'

that gets active/idle with no code, and it already handles the bash-preexec vs DEBUG-trap collision your poller would otherwise solve again. So the recipe's real delta is blocked and completed. Say that in How it works, a reader who only wants "is it running" needs one env var, not a poller.

for the PR:

• the poller needs a stop condition of its own. A hard-killed app runs no teardown and no SIGHUP reaches the process, because the pty's session leader is the surviving login, so it keeps polling forever. The codex adapter uses a token file plus a check cap and breaks when the pane read fails; hud.sh uses kill -0 on the app's pid. Pick one, don't ship without either.
• your poller is the only writer of that glyph. If it dies after active --blink the row pulses forever with nothing to correct it. Codex gets rescued by its next hook event, kiro has none. Worth a recovery path, and a line in Limits either way.
• session.text has no --pane-id, and with --pane omitted it reads the on-screen surface, so an open scratch feeds the matcher a different program's screen. AGTERM_PANE also goes stale after a split survivor is promoted (agent-status mis-attributed to the wrong pane after promote + re-split (baked AGTERM_PANE) #199), and --pane right on a promoted survivor errors. Two kiro runs in one split share a session id as well.
• the version floor is 0.5.0, not the 0.3.1 the kimi recipe carries: session.text shipped there, and --pane scratch for it in 0.7.0. Work it out from the flags you actually use.
• bound the matching the way the codex adapter does, tail -n 12 and lowercased, and make the anchor strings an overridable variable. Pin 2.16.1 in Requirements as the version they were read from. Fish gets no linting in CI, only .sh, .zsh and .py, so say so in the PR.

on the trigger itself: a kiro() wrapper function instead of preexec matching makes it exact, aliases included, and a trap on command kiro returning gives both the stop condition and the terminal completed for free. That deletes the regex, the token file and the alias caveat in one move. Your call though, the preexec version is fine if you'd rather stay close to the shipped integration.