Skip to content

Coding agents: hooks for Kiro CLI #798

Closed

Description

@LoopGlitch26

Kiro CLI, the terminal coding agent that succeeds Amazon Q Developer CLI, runs command hooks around tool calls, and a PreToolUse hook can block the call (hooks, hook types, actions, tools). Tracekit has no Kiro support yet.

What the docs say (read 2026-11-13):

  • Where hooks are set. A JSON file per hook set in a project's .kiro/hooks/, and in ~/.kiro/hooks/ from CLI V3: {"version": "v1", "hooks": [{"name", "trigger", "matcher", "action": {"type": "command", "command": "..."}, "timeout"}]}. timeout is in seconds, 60 by default. 0 turns the timeout off. On CLI V3, hooks can also be inline in an agent config (.kiro/agents/, ~/.kiro/agents/, key hooks), as a flat array without the version wrapper.
  • Triggers: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart (alias AgentSpawn), SessionEnd, PreCompact, PostCompact and others.
  • Blocking. The command gets the session context as JSON on stdin. Exit 0 lets the call run. Any other exit code blocks a PreToolUse call and sends stderr to the agent. The docs show these stdin fields: hook_event_name, cwd, session_id, tool_name, tool_input. They don't say whether there is a tool call id, or what happens on a timeout.
  • Tools. Built-in tool ids include execute_bash (execute_pwsh on Windows), read_file, list_directory, file_search, grep_search, fs_write, fs_append, str_replace, delete_file, web_fetch, remote_web_search and invoke_sub_agent. MCP tools reach hooks as mcp_<server>_<tool>. The docs don't give the tool_input fields of the shell and file tools. CLI 2.x used other names (read, write, shell; built-in tools), and the migration notes say the old names still work.

Things to design around

  • The timeout. A held call waits up to APPROVAL_WAIT_S = 540 seconds for a person (tracekit/integrations/claude_code.py:102), and Kiro's default timeout is 60. Init has to write a timeout above 540 (or 0, no timeout) in the hook file. Find out in step 1 what Kiro does when a hook times out; if the call then runs, that goes in docs/limits.md.
  • Call ids. If PreToolUse and PostToolUse carry no shared call id, pair them with _paired_ids (tracekit/agent_hooks.py:511) and add kiro to PAIRED (line 736), as Gemini CLI, Droid, Antigravity, Devin and Cline do.
  • MCP names. mcp_<server>_<tool> can't be split cleanly when the server name has a _ in it. Record what Kiro sends for such a server in step 1, and don't guess the split.
  • Kiro's own config. An agent that edits .kiro/hooks/ or .kiro/agents/ can turn Tracekit's hook off. .kiro belongs in the harness-config rules of the coding pack, TK-F009 and TK-F015 (tracekit/policy2/packs/coding.yaml, the (codex|gemini|opencode|…|cline) group of both patterns), with a pack version bump. Several open PRs change that pack right now, so take the line numbers and version from main when you open the PR.

Task

  1. Record real PreToolUse, PostToolUse and session events from Kiro CLI on macOS or Linux (the stdin JSON; redact anything private) as cases in tests/data/harness/kiro.json, next to the other harnesses' files there (codex.json, qwen.json, …). In the PR, give the Kiro CLI version, the tool_input of execute_bash, fs_write, fs_append, str_replace, delete_file and an MCP call, whether a call id is there, what a hook timeout does, and which tool names (the V3 ids or the 2.x ones) hooks receive.
  2. Add kiro to AGENT_NAMES (tracekit/agent_hooks.py:87), map its tools in tool() (line 318), under the names step 1 recorded: execute_bash and execute_pwsh to Bash, read_file to Read, fs_write and fs_append to Write, str_replace to Edit, delete_file to a delete the policy sees, web_fetch to WebFetch, and mcp_<server>_<tool> to the MCP form the other harnesses use. Map its events in normalise() (line 551).
  3. tracekit init --dev [--v2] --agent kiro, uninstall and doctor: write Tracekit's hook file in ~/.kiro/hooks/ (config_path, line 1029; install, line 1575), with Tracekit's own name so uninstall removes only that file. Kiro loads ~/.kiro/hooks/ only from CLI V3, so init and doctor check the installed version (kiro-cli --version or what step 1 finds) and say so on an older one.
  4. Tests in tests/test_agent_hooks.py (the mapping, the installer and uninstall), and the recorded cases through cases("kiro") (tests/test_harness_hooks_v2.py:36).
  5. A column in docs/coding-agents.md, and docs/limits.md rows for what Kiro's hooks can't see.

Done when: in a real Kiro CLI session (name the version in the PR), a denied call is blocked and the model sees the reason, a held call waits for tracekit approvals approve, the session's calls show up in tracekit last, and make test passes.

Comment here to claim it. Commits need a DCO sign-off (git commit -s).

Activity

  1. khushi-git-7 commented on Nov 13, 2026

    @khushi-git-7
    Contributor

    I'd like to take this one.

    Plan, following the task list:

    1. Record first. I'll run Kiro CLI with a hook that only writes its stdin to a file, then put the events into tests/data/harness/kiro.json. The PR will report:
      • the version;
      • the tool_input of each tool you listed, and of an MCP call (I'll use a server with a _ in its name, to see what mcp_<server>_<tool> looks like);
      • whether a call id is there;
      • what a hook timeout does, tested with a short timeout and a hook that sleeps past it;
      • which tool names hooks receive.
        Nothing gets mapped before that.
    2. Map. Add kiro to AGENT_NAMES, map the tools in tool() and the events in normalise(), under the recorded names. If there is no shared call id, pair the calls with _paired_ids and add kiro to PAIRED. MCP names are split only as far as the recordings show is safe.
    3. Install. init --dev [--v2] --agent kiro, uninstall and doctor. The hook file goes in ~/.kiro/hooks/ under Tracekit's own name, with a timeout above APPROVAL_WAIT_S, plus a version check that names CLI V3.
    4. Rules. Add .kiro to TK-F009 and TK-F015, with the pack version bump, both taken from main when I open the PR.
    5. Tests and docs. Tests in test_agent_hooks.py and through cases("kiro"), the coding-agents.md column and the limits.md rows.

    One question before I start. My machine is Windows 11, where Kiro CLI has run natively since 2.0, with execute_pwsh in place of execute_bash. I can record a real session there. I don't have macOS, and recording on Linux would mean setting up WSL. Would Windows recordings work for step 1 and the done-when session? Or do you need at least the Linux side, in which case I'll set up WSL first?

    #722's (2) and (3) carry on in parallel; they're on a separate branch.

  2. LoopGlitch26 commented on Nov 13, 2026

    @LoopGlitch26
    MemberAuthor

    It's yours, and recording first is the right order. Put the recorded payloads in tests/data/harness/kiro.json (as the other harnesses do) with the Kiro CLI version, and note anything the docs leave out that the recording settles. #722 can wait for this or run alongside it, whichever suits you.

  3. khushi-git-7 commented on Nov 13, 2026

    @khushi-git-7
    Contributor

    Draft PR: #825. The recorded payloads are in tests/data/harness/kiro.json (Kiro CLI 3.3.0, Windows 11). The PR lists what the recording settled that the docs leave out: only exit 2 blocks; a failed, unstartable or timed-out hook lets the call run; no call id; delete_file names its file targetFile; MCP names are mcp_<server>_<tool> with tool_load before them; no SessionEnd in --no-interactive. It stays a draft until the live session with Tracekit in the hooks is done.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions