Skip to content

feat(acp): route claude Agent-tool children per session on the shared runtime - #37601

Merged
chenmingwei23 merged 1 commit into
mainfrom
feat/claude-shared-children
Nov 15, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
feat/claude-shared-children

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

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's sessionId) 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's subagent_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.

  • Route. runtime_frame_accounting._note_announced_child learns a subagent_update's child (update.sessionId) as the announcing session's, under the same NATIVE_CHILD_ROSTER_CAP. The route is kept until the owner leaves, because an idle claude child can still be messaged.
  • Handle (acp/session_handle_claude_children.py, read first by _handle_update), calling client_native_children's own functions with the handle as reader:
    • a subagent_update merges 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;
    • a session_message on the child's session links the Agent call and fills a missing task (_note_session_message);
    • a child listed in an earlier turn is listed again on its first frame of this turn, recognised by its kept row;
    • an adapter notice addressed to the child is its card text;
    • a tool call on the parent's session stamped with a known child's Agent call is that child's activity, then the parent's ordinary row; one stamped with an Agent call this session has no link for (refused at its cap) is still marked a child's (_untracked_child_call), so its directive cannot act on the parent's chat.
  • Child lifetime. As on the per-chat client, claude child ids are bounded for the session's life, not per turn: the turn reset keeps them, and _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 own StreamRedactor across 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's subagent_update that 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.
  • Stop. cancel_native_child sends session/cancel naming 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 by native_child_requests. AcpSessionProvider forwards both (session_provider_native_children), so dashboard.native_child_stop reaches them through the slot's client.
  • Child questions (every backend). The reader routes an announced child's elicitation/create to 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 under mcp_elicitation with 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/create that 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 where client_capabilities_for(backend) declares subagents (claude). A kiro-cli or KAS slot's provider now answers cancel_native_child with 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.

  • A child's card, delegated prompt, text and tool call reach chat A's turn as card events, never as A's transcript text or tool rows, and chat B's turn sees none of them; frames stamped onto the parent's session go on the child's card.
  • The child's route is A's; a Stop through A's provider sends session/cancel naming 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.
  • A child's permission request is kept for its Stop in A and not in B.
  • A child that outlived a turn is read on its first frame of the next; a child call with no Agent-call link is still marked a child's.
  • Child ids and last turn's refusals outlive the turn start, and a finished child is not counted resident on a later turn.
  • A credential split across two parent turns stays masked, whether the first turn ended on end_turn or max_tokens.
  • A child that finishes between parent turns is settled by the next turn: not working, not stoppable.
  • A child's question reaches its own chat's turn; with no turn reading it is declined and recorded; a question no session owns is declined and recorded; a decline waits on the shared answer bound.

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.94 subagent_update this 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

  • 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.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 15, 2026
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision b5a8cd60b30754ed9f0c709e6ba5e8ffab11d698 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of b5a8cd60b30754ed9f0c709e6ba5e8ffab11d698 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • The only behaviour change for every backend: an unowned elicitation/create is now declined instead of dropped. Previously the asking tool waited until it timed out, so this only adds an answer and takes nothing away.
  • The rewritten test_a_kiro_native_card_closes_alone still pins the decision it was written for: a kiro card closes on its own. Only the mechanism changed, from "no such method" to "asked and declined", so this is not a pin being weakened.

[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 .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

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of b5a8cd60b30754ed9f0c709e6ba5e8ffab11d698 — 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

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

  • Item 6 — rides along: declining unowned elicitation/create changes behaviour on every backend, but the Goal covers only "a claude chat on the shared ACP runtime". The harm, "A dropped question left the asking tool waiting until it timed out", has no linked issue. Only the tests this PR adds support it. Subtraction: limit the second new decline branch in _reader_loop (the one sending _UNREGISTERED_REJECT_REASON or _ROSTER_OVERFLOW_REJECT_REASON) to announced children, so unannounced questions on other backends are left as they are on base.

What this change ships

Inventory (9 items) — 7 justified

Intent: 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.

  1. A claude child announced by subagent_update now gets a route to its parent chat on the shared runtime — justified
  2. The parent chat draws a card for each claude child, with its prompt, text and tool calls — justified
  3. A child's tool call stamped on the parent session goes on the child's card; an unlinked one is marked as a child's — justified
  4. Stopping a child from its card sends session/cancel for that child on the shared connection — justified
  5. A child's question is routed to its owner's turn and declined between turns — justified
  6. On every backend, a question no session owns is now declined and recorded instead of dropped — rides along
  7. A working claude child keeps its redactor across parent turns, and the resident count reports only this turn's children — justified
  8. A kiro-cli or KAS provider now answers cancel_native_child with False instead of lacking the method — justified
  9. The backend property tolerates a handle with no _runtime — undeclared

[FIRST-PRINCIPLES-REVIEWED] b5a8cd6

Description read

[DESCRIPTION-READ] 0fb55c3ae762572445e2103042b8146f883c513f753aed7a207c377f4fbedad8

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

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of b5a8cd60b30754ed9f0c709e6ba5e8ffab11d698 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b5a8cd6

False positive or not applicable? A repository writer can comment:
/ai-review override gpt b5a8cd60b30754ed9f0c709e6ba5e8ffab11d698 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed b5a8cd60b30754ed9f0c709e6ba5e8ffab11d698 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] b5a8cd6

Verdict parsed from the review's SHA-scoped output markers for commit b5a8cd60b30754ed9f0c709e6ba5e8ffab11d698.

False positive or not applicable? A repository writer can comment:
/ai-review override fable b5a8cd60b30754ed9f0c709e6ba5e8ffab11d698 false-positive: <reason, 20 to 500 characters>

@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-children branch from afa7ee9 to 1befab0 Compare November 15, 2026 12:40
@KiroCrewCaptain

KiroCrewCaptain commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: 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 b5a8cd60b3 · 1299 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-children branch from 1befab0 to a7b6614 Compare November 15, 2026 12:54
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-children branch from a7b6614 to 5e99e65 Compare November 15, 2026 14:04
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-children branch from 5e99e65 to 66c4d1a Compare November 15, 2026 15:46
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention labels Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-children branch from 66c4d1a to 21ade13 Compare November 15, 2026 16:25
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-children branch 3 times, most recently from 9cdcab0 to df01049 Compare November 15, 2026 17:09
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-children branch from df01049 to 0e0e8c3 Compare November 15, 2026 17:55
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-children branch 5 times, most recently from 192fdd3 to 6c8c640 Compare November 15, 2026 19:19
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-children branch from 6c8c640 to 9f7c283 Compare November 15, 2026 19:35
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-children branch from 9f7c283 to 16dd524 Compare November 15, 2026 19:37
… 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.
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-children branch from 16dd524 to b5a8cd6 Compare November 15, 2026 19:48
@chenmingwei23
chenmingwei23 enabled auto-merge (squash) November 15, 2026 20:35
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 15, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/userInput and _kiro/mcp/elicitation, not only elicitation/create as the body and acp-client.md say. Either narrow the check to elicitation/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.

@chenmingwei23
chenmingwei23 merged commit c6fa41b into main Nov 15, 2026
99 checks passed
@chenmingwei23
chenmingwei23 deleted the feat/claude-shared-children branch November 15, 2026 21:44
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants