[idea] Add Kiro CLI direct integration

[s-miyama-nyle]

idea / problem

Kiro CLI (kiro-cli) is detected by herdr via screen manifests (working/blocked/idle), but session identity is not reported. After a herdr server restart, Kiro panes are restored as bare shells — the conversation cannot be resumed automatically.

requested change

Add herdr integration install kiro / herdr integration uninstall kiro that installs a session-identity hook following the same pattern as Copilot, Cursor, and Droid.

The hook script reports pane.report_agent_session at SessionStart. Kiro CLI's v3 agent engine executes .sh files placed in ~/.kiro/hooks/. State detection remains screen-manifest-based.

I already implemented this and verified it works:

• Branch: s-miyama-nyle/herdr@feat/kiro-integration (+187 lines, 9 files)
• cargo check, cargo clippy, cargo test --bin herdr (2702 tests) pass clean
• Hook fires on kiro-cli chat --v3 and successfully reports session ID to socket
• Kiro CLI resume command: kiro-cli chat --resume-id <session_id>

Note: Kiro CLI's default (v2) engine does not load standalone hooks yet. The v3 engine does and is expected to become default.

why you want this

I run multiple Kiro CLI sessions in herdr daily. Without session restore, every server restart loses all active conversations and requires manual re-launch with --resume-id (after looking up each session ID).

I intend to open a PR if this direction is approved.

[oafish]

+1 on this. I'm running Kiro CLI daily in herdr and losing sessions on server restart is the main pain point.

I looked at the branch and have a few notes that might be useful.

Session ID source. The hook scans ~/.kiro/sessions/ for the most recently modified session.json. This works but has a race window — if two Kiro panes exist, the scan could pick up the wrong session. Kiro CLI already sets $KIRO_SESSION_ID (a UUID) in the hook's process environment at session start. Reading that directly is simpler and always correct for the calling pane:

session_id = os.environ.get("KIRO_SESSION_ID")
if not session_id:
    raise SystemExit(0)

I just verified KIRO_SESSION_ID is present in the current shell (2.15.1)

Resume plan is missing. The branch reports session identity to herdr, but agent_resume.rs doesn't have a ("herdr:kiro", "kiro") entry in is_official_agent_source() or plan(). Without that, herdr persists the session ref but can't build the resume argv after a restart. The entry would be:

("herdr:kiro", "kiro", AgentSessionRefKind::Id) => {
    vec!["kiro-cli".into(), "chat".into(), "--resume-id".into(), session_ref.value.clone()]
}

session_identity_only_integration registration. For the persisted session ref to survive process exit and be used on restore, detect/mod.rs needs:

pub(crate) fn session_identity_only_integration(source: &str, agent_label: &str) -> bool {
    matches!(
        (source, agent_label),
        ("herdr:hermes", "hermes")
            | ("herdr:kiro", "kiro")
    )
}

Without this, set_hook_authority_at returns None for session-identity-only sources and the session ref never reaches TerminalState.

v3 hooks format. The v3 docs (kiro.dev/docs/cli/v3/hooks/) show standalone .kiro/hooks/<name>.json files with a "version": "v1" schema. The triggers are the same (SessionStart, Stop, PreToolUse, etc.) but the format is different from the agent-embedded hooks. The current branch approach (placing a bare .sh in ~/.kiro/hooks/) works with the v2/current engine. For v3, the hook might need to be wrapped in the JSON envelope, or Kiro v3 might still auto-run plain scripts alongside JSON hooks — worth verifying when v3 ships as default.

What works today. With 2.15.1, ~/.kiro/hooks/*.sh files are auto-executed on SessionStart. So the integration already works for current users. The $KIRO_SESSION_ID fix and the two agent_resume.rs additions would make it a complete session-restore integration.

Happy to test a patched build if it helps move this forward.