Skip to content

feat(chat): give a turn the agent starts its own labelled group - #30786

Open
rinbn wants to merge 3 commits into
kirodotdev:mainfrom
rinbn:feat/agent-started-turn-label
Open

rinbn wants to merge 3 commits into
kirodotdev:mainfrom
rinbn:feat/agent-started-turn-label

Conversation

@rinbn

@rinbn rinbn commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On the claude backend, a turn Claude Code starts on its own shows in the chat as its own group headed by "Started by the agent", instead of as more rows of the previous user turn.

Since #30092, a turn Claude Code starts on its own shows up on time: a run_in_background command finishes and the model answers, or a background or Workflow agent asks for a permission. But it renders as ordinary rows. The chat page and the chat pane group its tool rows and its reply with the user turn before it, so nothing tells the reader that the agent spoke unprompted, and the agent's tool calls read as part of the earlier answer. #30092 left the RFC's label out of scope. It also marked only the agent's assistant rows (meta.origin = {"kind": "agent"}), so a turn that ran tools and wrote no reply carried no mark the transcript could find.

Why it matters

Anyone on the claude backend who starts background work reads the result in the wrong place. The agent's follow-up looks like more of the answer they already read, the tool rows it ran look like steps of that earlier answer, and nothing on screen says the agent acted without being asked. A turn that only ran a tool (for example, started the next background job) is the hardest case: it has no reply to point at.

Not a goal

  • The closing origin's reason on the row. The transport reads it and does not hand it to the dashboard; exposing it is a transport change, left out here.
  • Any backend other than claude, and any session the dashboard chat does not run (channel sessions, cron sessions, sub-agents). They write no such row, as on main.
  • A separate label per origin, or a setting for the label. agent.agent_started_turns already turns the whole feature off.

What changed (motivation → approach → change)

Design record: the RFC's section 3 and Phase 2 exit criteria (docs/request-for-change/rfc-agent-started-turns.md, status partial). This builds on #30092's implementation.

  • Which row is marked, and why that one. The turn's first row, whatever its role, carries meta.origin = {"kind": "agent", "turn_start": true}. The transcript needs to know where the agent's turn starts, because the turn has no prompt row to open it, and the first row is the one row every turn that shows anything has. A tool-only turn has no assistant row and no footer row (turn_stats goes on the reply row), so neither of those could carry the mark. The first row also arrives first, so the group and its label show while the turn is still running, not only at its end. The assistant rows keep feat(chat): show claude agent-started turns and their permission cards #30092's {"kind": "agent"}.
  • How it is written. When the agent-started turn opens its stream, it leaves the opener meta owed on its slot (slot._owed_turn_opener = agent_turn_opener_meta, in chat_runner.py). The slot's append (state_parts/slot_transcript.py) puts it on the next durable row it writes, after any segment cut a permission request owes (so the cut's text row is the first), and never on a user row or a wire-only row (chunk, streaming, done). A turn that wrote no row drops the owed meta when its stream closes (agent_started._close_agent_turn_stream), so the next unrelated row is never taken for the agent's. The row is persisted with the meta like any other, so a reload and a resumed session group it the same way. User turns and every other backend never set it.
  • Grouping. groupDisplayItems (the chat page) and app-sdk ChatMessageList (the pane) start a new turn group at a row that opens an agent-started turn, flush the turn before it there, and mark the group agentStarted. A marked group always wraps as a turn, a lone reply included, so it is always headed. The group runs to the next prompt row or the next agent turn's first row. The chat page shows permission requests in the approval bar rather than as rows, so when the opener is a permission row it opens the group at the next row it shows. The pane never lets a grouped reasoning or permission run span the start of an agent turn.
  • Label. TurnBlock draws "Started by the agent" (a bot icon, muted text, a tooltip saying the agent answered on its own) as the first row of a marked turn, above its fold toggle, its tool rows and its reply. Theme tokens only, so light and dark both follow the theme. The two strings are in en.manual.json, all 11 translated catalogs and the regenerated pseudolocale.
  • Regenerate. is_agent_started_row reads any marked row, so Regenerate's agent_started_reply refusal now also covers a turn that wrote only tool rows after the newest user row, which a re-run would otherwise delete.
  • Docs. claude-code-provider.md ("A turn Claude Code starts on its own") describes the opener and the grouping; learn-cron-dashboard.md's owner row lists the new meta; the RFC's status note no longer says the label is unbuilt.

Known limits, each by design or out of reach for the transcript:

  • Rows saved before this change carry no opener, so a turn the agent started before it renders as it does on main.
  • On the chat page, a turn whose only row is a permission request shows nothing in the transcript (the approval bar shows the request), so it has no group to head; if nothing else of that turn is shown, the opener passes to the next row the transcript shows.
  • A turn the agent started inside a sub-agent fan-out that a later synthesis folds into one interim turn loses its own group and label inside that fold, as every turn in the fold does.

Backwards compatibility

Breaking: Regenerate is refused with agent_started_reply when the rows after the newest user row include a turn the agent started that wrote only tool rows. Main accepted that request and the re-run deleted those rows. Writer sweep on origin/main @ b764e20: is_agent_started_row has one caller, chat_regenerate.py's refusal check; chat_runner.py only re-exports it. No other code reads a row's meta.origin as an agent mark.

Reader: src/kiro_crew/dashboard/chat_regenerate.py:api_chat_slot_regenerate -- entry: chat -- test_regenerate_refuses_a_span_holding_a_reply_the_agent_started (new tool-only case)

Tests

test/test_dashboard_agent_started_turn.py (backend, through _run_chat(_agent_started=True)):

  • test_a_turn_of_only_tool_rows_is_marked_on_its_first_row: a turn that ran one tool and wrote no reply carries the opener on its tool row, in memory and in the saved transcript, and a row written after the turn carries none.
  • test_only_the_turns_first_row_opens_it_and_its_reply_is_in_the_resume_replay: text, tool, text: only the first row carries turn_start, the later reply keeps {"kind": "agent"}, the saved transcript keeps the opener, and the reply is in the session replay a resumed session gets.
  • test_a_turn_that_wrote_no_row_leaves_no_opener_for_a_later_row: an empty turn drops the owed meta.
  • test_the_first_durable_row_the_turn_writes_takes_the_opener: wire-only and user rows are skipped, and the row a permission's segment cut writes takes the opener before the permission row.
  • The two existing reply tests now expect the opener on the reply, which is that turn's first row; test_regenerate_refuses_a_span_holding_a_reply_the_agent_started gains a tool-only case.

website/src/test/TurnBlock.agentStarted.test.tsx: in the chat page's grouping and TurnBlock, and in the pane's ChatMessageList, the order is label, tool-call toggle, tool row, reply, with the fold closed and open and exactly one label; a tool-only turn and a lone reply are headed too; a prompted turn draws no label. website/src/test/groupDisplayItems.test.ts: the agent turn's own group from its first row to the next prompt; a tool-only turn and a lone reply wrap; the rows before the opener stay with their turn even when that turn left no footer; a second agent turn starts at its own first row; a permission opener hands over to the next shown row; an agent reply with no opener groups as before; the running agent turn is the trailing turn.

Each new backend test fails with its part of the fix removed (not setting the owed meta: 4 tests; append ignoring it: 5; not dropping it at the turn's end: 1). With TurnBlock's label removed, 6 of the 7 rendering tests fail; with the grouper never opening an agent turn, 9 tests fail.

Results: the backend files around the change pass, 1,670 tests in 45 files at -n 4 (agent-started turn, state-parts facade and dashboard state, chat slot, transcript ordering and readers, permission cut, regenerate, approval, composition contract, slot readers, timeout consistency, bindings); the frontend set scripts/run_scoped_tests.py --surface frontend relates to the diff passes, 14,259 tests in 519 files. After the last rebase onto main the agent-started turn, facade, composition and slot-reader suites (201 tests) and the two frontend files (62 tests) were run again and pass, as do tsc and i18n:check. flake8, isort, black (touched files), check_harness_parity.py, the black and subprocess-encoding ratchets, check_file_line_cap.py, docs-lint.sh, eslint, lint:i18n, lint:theme-colors, lint:phantom-classes and lint:restyle-ratchet pass. mypy reports two errors, both in apps/routes_registry.py, which this PR does not touch and main carries.

Manual verification

The browser-harness frames below come from website/scripts/capture-17566-agent-started-reply.mjs, which serves website/capture/agent-started-reply.html (the chat pane with the real stylesheet, theme tokens and catalogs) from an in-process vite server on 127.0.0.1 and checks each frame: every "after" and "tool-only" frame draws exactly one label, above the turn's tool-call toggle; every "before" frame draws none. All six frames passed.

Not run against a live claude-agent-acp in this PR: the marking is written by the same append every row goes through, which the backend tests drive through the real runner.

Screenshots / video

The chat pane with the same conversation: a background command, the turn the agent starts when it finishes, then "status?". After: the agent's turn is its own group, headed by "Started by the agent", then its "1 tool call" row and its reply. Before (main): the same rows with no label, under the earlier turn.

After, light

After, dark

A turn that wrote only a tool row is headed the same way:

Tool-only, light

Tool-only dark, and before (main)

Tool-only, dark

Before, light

Before, dark

The images are committed under temp-screenshots/17566-agent-started-reply/ because this is a fork PR, which cannot use --attach.

Related Issues

Part of #17566

Builds on #30092, which shows the turn; this adds the RFC's label and the turn's own group.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@rinbn
rinbn requested review from a team and KiroCrewCaptain as code owners November 5, 2026 22:05
@rinbn
rinbn requested a review from buluoray November 5, 2026 22:05
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Nov 5, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 10, 2026
@rinbn
rinbn force-pushed the feat/agent-started-turn-label branch from 8e2c334 to 8cd6bf7 Compare November 11, 2026 17:10
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 11, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 12, 2026
@rinbn
rinbn force-pushed the feat/agent-started-turn-label branch from 8cd6bf7 to cf559e1 Compare November 12, 2026 19:09
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 12, 2026
rinbn and others added 2 commits November 19, 2026 23:29
On the claude backend a turn Claude Code starts on its own now shows
on time (kirodotdev#30092), but as ordinary rows in the previous user turn's
group: nothing says the agent spoke unprompted, and its tool rows read
as part of the earlier answer. Only its assistant rows were marked, so
a turn that ran tools and wrote no reply was not marked at all.

The turn's first row, whatever its role, now carries meta.origin
{kind: agent, turn_start: true}. The turn owes that meta to its slot
when it opens its stream, and the next durable row append writes takes
it; a turn that wrote no row drops it when its stream closes. The chat
page grouper and the pane's ChatMessageList start the agent turn's own
group at that row, and TurnBlock heads the group with a "Started by
the agent" label above its tool rows and its reply. Regenerate's
refusal now also covers a turn that wrote only tool rows. Kiro and the
other backends write no such row.

Refs kirodotdev#17566
kirodotdev#38313's request-wait test predates turn_start; the reply is that turn's
only row, so it carries the opener origin.
@iamwhatever
iamwhatever force-pushed the feat/agent-started-turn-label branch from cf559e1 to ecb761d Compare November 19, 2026 23:33
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention labels Nov 19, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of ecb761da7fe7680cfab061f374beeb0eb2dd4315 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the turn's first row is marked through the slot's one append seam, persisted with the row, and dropped when the turn closes. Rendered evidence is committed, and the stricter Regenerate refusal is listed as breaking.

Notes

  • The opener is owed to the slot, not to the turn. append hands it to the next durable non-user row, whoever writes it: if owed_opener is not None and role not in _WIRE_ONLY_ROLES and role != "user". If another writer adds a row to the slot (a gateway notice, an error row) after the agent's turn opens its stream and before its first row, that row gets turn_start and opens the group instead. The cost is a wrongly placed label, and a revert or a role check undoes it. Paying the opener only from the turn's own row writers (tool, assistant, permission) would remove that case.

[DESIGN-REVIEWED] ecb761d

Description read

[DESCRIPTION-READ] 3a165a09c3452a088e4e63e759ee6bdef28ab7010286f4764738bf7ead86fab2

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ✅ PASS

UX-level review of ecb761da7fe7680cfab061f374beeb0eb2dd4315 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

This lane has no blind read: a first-time reader has not seen the "Started by the agent" label, which the committed screenshots (dark and light, reply turn and tool-only turn) do show. Pushing the branch to this repository runs the blind read.

Notes

  • The agent_started_tooltip lives only in a native title, so keyboard and touch users never see it. That costs little because the label carries the meaning; only move it into a focusable tooltip primitive if the explanation matters.
  • In a tool-only turn, "The agent answered on its own…" describes a reply that never happened (tool-only-dark.png and tool-only-light.png). "The agent acted on its own, for example after a background task it started finished." fits both kinds of turn.

[UX-REVIEWED] ecb761d

Description read

[DESCRIPTION-READ] ec855f269a954d0b9749608a64d670afbba44ef1dea6e7f8b5e664d83afbad85

That sha256 names everything this verdict read: the PR description, plus the 9 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of ecb761da7fe7680cfab061f374beeb0eb2dd4315 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Every item traces back to the accepted partial RFC's label and Phase 2 browser frame, which were never built. One note: the slot field accepts any callable, but only one function is ever stored in it.

Notes

  • Item 2 — one consumer, generalized: _owed_turn_opener: Callable[[dict | None], dict] | None has exactly one assignment site, slot._owed_turn_opener = agent_turn_opener_meta (chat_runner.py; grepped _owed_turn_opener = across the patch: one non-None write). Subtraction: make it a bool, _owes_turn_opener, and have append call agent_turn_opener_meta directly. Keep the callable only if importing chat_turn from state_parts would create a cycle.

What this change ships

Inventory (7 items) — 6 justified

Intent: on the claude backend, a turn the agent starts on its own reads as its own labelled group, not as more rows of the previous answer. ADDITION, covered by the RFC (§ "only visible addition" label, Phase 2 frame).

  1. A turn the agent starts now shows as its own group in the chat page and the pane, not folded into the previous user turn — justified
  2. That turn's first saved row of any role now carries meta.origin.turn_start: true; an empty turn writes no mark — one consumer, generalized
  3. The "Started by the agent" label with a bot icon and tooltip heads that group — justified
  4. A permission-only opener hands the group start to the next row the chat page shows — justified
  5. Regenerate now refuses when the agent's turn wrote only tool rows, where before it deleted them — justified
  6. Two new strings in 12 locale catalogs — justified
  7. A capture harness, a capture script and six screenshots — justified

[FIRST-PRINCIPLES-REVIEWED] ecb761d

Description read

[DESCRIPTION-READ] 41659957504b96b03138ff2bb8882a5ad27a4995ca706546683277f2e75cf284

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed ecb761da7fe7680cfab061f374beeb0eb2dd4315 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] ecb761d

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — 🔴 changes requested (blocking)

Reviewed ecb761da7fe7680cfab061f374beeb0eb2dd4315 via the fork AI-review pipeline; updated in place on each push.

Adjudication upheld 1 of 1 blocking finding(s); those must be resolved before merging.

BLOCKING -- src/kiro_crew/dashboard/state_parts/slot_transcript.py:332 -- Permission-first turns lose their boundary on refresh and resume

if owed_opener is not None and role not in _WIRE_ONLY_ROLES and role != "user":
Trigger: An agent-started turn requests interactive approval before writing text or tools. _run_chat → _on_permission_prompt → slot.append("permission", ...) consumes _owed_turn_opener, leaving subsequent tools and replies without turn_start.
Outcome: Refresh folds those rows into the preceding user turn without the label: _prepare_messages replaces permission metadata from cls, preserving only mid. Resume also loses the boundary because persistence excludes permission rows via _TRANSIENT_ROLES.
Anchor: defect
Fix: Preserve the permission opener through HTTP serialization and retain an opener for the first persisted, non-transient row.

[BLOCK-MERGE] ecb761d
[GPT-REVIEWED] ecb761d

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1 stays blocking: the harm is moderate and the real fix is about one line.

  • Harm: MEDIUM. On a common path, the very label this PR adds goes missing after a refresh or resume, and nothing tells the user. Confirmed: the interactive approval writes its row at permission_prompt.py:368. permission is not in _WIRE_ONLY_ROLES (transcript_rows.py:631), so under the diff's slot_transcript.py:332 that row takes the opener. Refresh then rebuilds the row's meta from cls and keeps only mid (chat_utils_display.py:1353-1362), and permission is in _TRANSIENT_ROLES (transcript_rows.py:613), so it is never saved. There is no recovery: later rows never get an opener.

  • Fix cost: about one line. Exclude transient roles in the opener condition, so the first durable row takes it. That needs no new state and no coordination between modules.

    [ADJUDICATION] ecb761d total=1 uphold=1 downgrade=0
    UPHOLD F1 src/kiro_crew/dashboard/state_parts/slot_transcript.py:332 reason=harm-warrants-remedy
    [GPT-ADJUDICATED] ecb761d

A permission or elicitation card is transient: it is never saved and a
refresh rebuilds its meta, so a card-first turn lost its boundary on
refresh and resume. The opener now skips _TRANSIENT_ROLES.
@iamwhatever

Copy link
Copy Markdown
Contributor

Rebased onto main (conflicts in the RFC status line and the ChatMessageList.tsx import, both kept; one test from #38313 now expects the opener on a reply-only turn). The GPT 6.1 finding is fixed in ec67f87: the turn opener now skips transient rows (_TRANSIENT_ROLES, so permission and elicitation cards), and the first saved row takes it. New test: test_a_card_first_turn_leaves_the_opener_for_the_first_saved_row. Spec updated in claude-code-provider.md.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 19, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 20, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Status on head ec67f87: every CI and Build job passes. PR Readiness stays pending because Issue Gate and the fork AI-review lanes (GPT 6.1, Opus 5.5, Design, UX, First Principles, Security Scope, Internal Content Scan) never started on this head; their PR comments still show the older head ecb761d. A maintainer needs to retrigger those lanes on ec67f87 so the GPT fix (opener skips transient rows) is re-reviewed.

This branch has not been deployed

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

Labels

fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants