docs(coding-agents): Kiro CLI application session tracing (TH-8287) - #928

Guard commands, use a CLI-specific install scope, remove PreToolUse, and document V3 tool ids.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

…/th-8287-kiro-cli

Co-Authored-By: Claude Opus 5.5 <[email protected]>

… resume-safe SessionEnd (TH-8287)

- Every shipped command (project file, global file, agent-profile entries,
  page snippets) is the canonical subshell guard `(python3 -B <emit.py>
  kiro_cli <Trigger> 2>/dev/null || true)` with the trigger on argv. The
  bare `|| true` form fed a trailing heredoc to `true`.
- tests/test_kiro_cli_hooks_config.py runs every shipped command through
  sh/zsh/bash/dash with the payload on stdin and as a heredoc: emitter
  missing, python3 missing, installed (project, --user from another
  workspace, --user with KIRO_HOME, --agent-profile); exit 0, empty stdout,
  payload verbatim, no __pycache__, plus the unparenthesized regression and
  installer refusal cases.
- Observe-only: the global template no longer registers PreToolUse (gating)
  and the adapter ignores it; tool spans come from PostToolUse without a
  duration; kiro.tool.name (duplicate of gen_ai.tool.name) dropped.
- SessionEnd is not terminal (`kiro-cli chat --resume-id` reuses the session
  id): it closes a still-open turn (kiro.turn.ended_by=SessionEnd) and keeps
  the session state, so a resumed chat continues at turn-2 under the same
  root instead of overwriting turn-1. Tests for resume and Ctrl+C.
- Templates renamed to fi-hook-to-otlp-kiro-cli*.json (the names installed);
  no sed rewrite. install.sh honours KIRO_HOME (writes that path into the
  commands), refuses where the Kiro IDE recipe is installed (project or
  ~/.kiro/hooks) and a project install when the global one exists, says when
  an existing file is stale, and adds --agent-profile (emitter only, prints
  the agent-profile hooks from agent-profile-hooks.json).
- Fixture/page use the V3 tool id file_search; page: install paths and
  KIRO_HOME claim match the installer, guard explained, Windows caveat,
  IDE-in-same-project section with the agent-profile path, SessionEnd row
  with the 2.25 changelog source, kiro.hook.trigger on every 2.x span,
  /upgrade-agent instead of `agent migrate`, incomplete-turn text matches
  the code, Uninstall section.
- run_e2e.sh HOOK_TRANSPORT=stdin|heredoc runs the installed commands.
- Merged the foundation head 9b77d51 (emit.py prints nothing on failure).

Co-Authored-By: Claude Opus 5.5 <[email protected]>

Co-Authored-By: Claude Opus 5.5 <[email protected]>

Bring in main's Ubuntu 24.04 build runner so the current-head docs checks use the supported Playwright environment.

Co-Authored-By: Claude Code <[email protected]>