Repository navigation
feat(acp): route claude Agent-tool children per session on the shared runtime - #37601
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: claude children use the same owner-routing rule codex-acp children already use, and the only change for other backends is answering child questions that used to get no reply. Notes
[DESIGN-REVIEWED] b5a8cd6 Description read[DESCRIPTION-READ] 72837044ab82d10ad57ffe65626f7683d7620e38ad2e9aaf4c64906295fe4b45 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. Every item comes from the claude-agent-acp wire form or a request that got no answer. The one item reaching past claude is declared and answers a request that was previously dropped. Notes
What this change shipsInventory (9 items) — 7 justifiedIntent: let a claude chat that shares one ACP process show, route and stop its Agent-tool subagents, as a per-chat claude chat already does. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] b5a8cd6 Description read[DESCRIPTION-READ] 0fb55c3ae762572445e2103042b8146f883c513f753aed7a207c377f4fbedad8 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
afa7ee9 to
1befab0
Compare
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own. The PR teaches the shared runtime to learn claude Agent-tool children from subagent_update and route their frames, permission requests and questions to the announcing session. It reads the child form on the session handle with the client's own functions and lets a person stop one child through the provider. Every claude-specific path is gated on the session declaring subagents, which only claude does, so non-claude turn resets, redactors and rosters are unchanged. Routing keeps first-announcement-wins and the 4096 route cap. Stop uses the client's gate, and a False answer still makes the dashboard close the card itself. The one change for every backend, declining a question no session owns instead of dropping it, is declared, bounded by the shared answer-task limit, SEL-recorded and tested. The two-chat tests drive the real reader loop and cover isolation, Stop, between-turn settling, credential masking across turns and question declines. Remaining issues are cosmetic or hardening only. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
1befab0 to
a7b6614
Compare
a7b6614 to
5e99e65
Compare
5e99e65 to
66c4d1a
Compare
66c4d1a to
21ade13
Compare
9cdcab0 to
df01049
Compare
df01049 to
0e0e8c3
Compare
192fdd3 to
6c8c640
Compare
6c8c640 to
9f7c283
Compare
9f7c283 to
16dd524
Compare
… runtime claude-agent-acp announces an Agent-tool child on its parent's session (subagent_update, keyed on the update's sessionId) and sends the child's work under the child's own id. The shared runtime learned only codex-acp's subagent_spawned, so a shared claude chat's child frames had no route: its updates were dropped and its permission requests answered fail-closed, and the chat drew no card for it. - The runtime's reader learns a subagent_update's child as the announcing session's, so the child's frames reach that session. - AcpSessionHandle reads claude's child form with the client's own functions and row shape (session_handle_claude_children): the card roster, the delegated prompt, a background child listed again, a child's notice as card text, and a parent-session call stamped with a child's Agent call. The child's other frames keep the handle's child arm, and its text goes through its own redactor. - A child granted capabilities.cancel can be stopped alone: cancel_native_child sends session/cancel naming it on the shared connection, and the requests each child asks are kept for that Stop (native_child_requests), both reachable through the provider. Tests run two chats on one runtime through the real reader loop.
16dd524 to
b5a8cd6
Compare
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approving. On this head the review read the whole diff and checked these points. A claude child is routed only to the registered session its first subagent_update arrived on, a registered session id is never taken as a child, the shared cap holds, and the owner's children are purged on unregister. Two chats on one runtime were run through the real reader loop: 52 tests in the new and changed files pass. 18 of the 23 mutations applied to the production hunks turn a named test red. Kiro and KAS sessions keep their per-turn clear, and their new cancel_native_child returns False, so their cards close on their own as before.
Done well: the handle calls the per-chat client's own claude child functions, and the Stop gate is split out as native_child_cancellable, so the two drivers cannot drift apart.
Security: chat B cannot see, answer or stop chat A's child, because each handle's rows hold only the children routed to it, and the two-chat tests assert this negative side every time. The Stop goes through the existing gate (a supported backend, a tracked working child granted cancel, never the parent's own id). Between the owner's turns, permission requests are answered fail-closed and questions are declined. Each decline is recorded in SEL off the event loop, uses the shared answer-capacity bound, and has a bounded reply write. Credential text a child's redactor holds stays masked across parent turns.
Optional:
- The new decline for questions no session owns matches all three elicitation methods, including the KAS
_kiro/userInputand_kiro/mcp/elicitation, not onlyelicitation/createas the body and acp-client.md say. Either narrow the check toelicitation/create, or document the KAS methods, add a KAS test, and stop labelling a non-child request a "child question" (runtime_reader_loop.py:804). - No test checks that a child's held text reaches the card before its completed roster (session_handle_claude_children.py:125). If that line is replaced with
pass, every related test still passes. An order assertion in the between-turn and within-turn tests would pin it. - No test checks that a child's question is noted for its Stop (session_handle_dispatch.py:1027). Asserting that chat A's native_child_requests includes the question id, and chat B's returns nothing, would cover it. The re-add and comment at session_handle_claude_children.py:129-132 are dead code and can go.
Problem / Motivation
Goal: a claude chat on the shared ACP runtime shows the cards of Claude Code's Agent-tool subagents, routes their work, permission requests and questions to that chat only, and lets a person stop one child from its card, as a chat on its own process does.
claude-agent-acp announces an Agent-tool child on its parent's session (
subagent_update, the child named by the update'ssessionId) and then sends the child's work under the child's own sessionId. The shared runtime learns a child's owner only from codex-acp'ssubagent_spawned. A claude child therefore has no route: its updates are dropped as unrouted, its permission requests are answered fail-closed, and the parent chat draws no card for it. Once claude chats share one process (#37540), a chat that uses the Agent tool would see its subagent's tools refused.Stack: this branch sits on main as one commit. #37540 and #37615 stack on top.
Why it matters
The Agent tool is one of Claude Code's main tools. Without this, every subagent call in a shared claude chat fails at its first permission request, and the user sees no card explaining what ran.
Not a goal
What changed (motivation -> approach -> change)
The shared runtime should treat a claude child as it treats a codex-acp child -> learn the owner from claude's announcement and read claude's child form on the handle with the client's own functions -> one route rule and one handle owner module.
runtime_frame_accounting._note_announced_childlearns asubagent_update's child (update.sessionId) as the announcing session's, under the sameNATIVE_CHILD_ROSTER_CAP. The route is kept until the owner leaves, because an idle claude child can still be messaged.acp/session_handle_claude_children.py, read first by_handle_update), callingclient_native_children's own functions with the handle as reader:subagent_updatemerges into the child's row (_note_subagent_update) and yields the roster; a child that ends has the text its redactor holds put on its card first;session_messageon the child's session links the Agent call and fills a missing task (_note_session_message);_untracked_child_call), so its directive cannot act on the parent's chat._start_native_child_turn(shared with the client) clears the turn roster and says last turn's refusals. The resident count reports this turn's children. A working claude child keeps its ownStreamRedactoracross parent turns, through any parent ending but a cancel, so a credential its text splits across a turn boundary is still read whole; its own end flushes it. A child'ssubagent_updatethat arrives between turns is applied to its row by the next turn's start drain before the frame is dropped, so a child that finished meanwhile shows ended and is not stopped.cancel_native_childsendssession/cancelnaming the child on the shared connection (runtime.send_notification), behind the client's own gate (native_child_cancellable). The permission and elicitation requests each child asks are noted in the dispatch and answered bynative_child_requests.AcpSessionProviderforwards both (session_provider_native_children), sodashboard.native_child_stopreaches them through the slot's client.elicitation/createto its owner while the owner's turn reads; between the owner's turns it is declined. A question no registered session owns (a child past the announcement cap, or never announced) is declined too, where the base reader dropped it with no answer. Each decline goes through the shared answer-task bound (_wait_for_answer_capacity) and is SEL-recorded undermcp_elicitationwith its reason (owner_no_active_turn, or the roster-overflow / unregistered reason the permission answer uses).Backwards compatibility
Changed for every backend: a child's
elicitation/createthat reaches the runtime with no owner turn reading is now declined and recorded instead of dropped unanswered, and an announced child's question is routed to its owner's turn. A dropped question left the asking tool waiting until it timed out, so this only answers a request that had no answer.Otherwise claude only: the new route rule acts on
subagent_update, which no other harness sends, and the handle reads claude's child form, keeps child ids across turns and settles between-turn updates only whereclient_capabilities_for(backend)declaressubagents(claude). A kiro-cli or KAS slot's provider now answerscancel_native_childwith False (its handle grants none), so its card still closes alone.Removes nothing: every change adds a route, a reader or a forward; the client's Stop gate and turn reset are split into functions both drivers call.
test_claude_native_child_stop's kiro runtime case now asserts the provider was asked and declined, instead of asserting it has no such method.Tests
test/test_claude_shared_children.py: two claude chats on one runtime, frames written to the runtime's stdout and read by its real reader loop.session/cancelnaming the child, through B's it sends nothing; a child granted no cancel is not stopped; a Stop that cannot be sent reports the child not stopped.end_turnormax_tokens.Each of these fails with its fix removed.
Proof: not provable -- other: feature PR, the mutations above are the check
Also run, serially:
test_session_handle_bindings,test_runtime_bindings,test_client_bindings,test_harness_parity,test_claude_native_child_stop,test_claude_native_subagent_cards,test_codex_native_subagent_cards,test_acp_runtime_pre_turn_drain,test_acp_elicitation, the shared-runtime claude tests, and the facade-mirror and flake-pattern guards.Manual verification
Not verified on a pod. The pod's claude-agent-acp is 0.89.1, which announces children as
subagent_spawned(the codex-acp shape the runtime already routes) rather than the 0.94subagent_updatethis PR reads. Three prompts on a shared claude chat asked the model to call its Task tool explicitly; none of the three streams showed a Task tool row or a child card, so no child was observed on either wire. The behaviour here is covered by the two-chat tests above only.Related Issues
Part of the claude chat sharing stack: #37521, #37586, #37593, this PR, #37540, #37615.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license.