Repository navigation
fix(acp): show Codex native subagents as their own Subagents cards - #23094
Conversation
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level concerns: the new route is limited to harnesses that declare Notes
[DESIGN-REVIEWED] 9db45f4 Description read[DESCRIPTION-READ] f65deef35b31c7ab37c68855fdb1690be8e06751dd75282b05132e4526ea3c15 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, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Every item fixes the reported missing card at the cause: the undeclared capability plus the unrouted lifecycle frames. The only open question is whether the SDK 1.x legacy-row reader is still needed. Notes
What this change shipsInventory (8 items) — 7 justifiedIntent: a Codex user who delegates to a native subagent sees that child as its own Subagents card, with identity, lifecycle and output. FIX.
[FIRST-PRINCIPLES-REVIEWED] 9db45f4 Description read[DESCRIPTION-READ] 9f03f63cafe4fb5660f07381818d87c251b9c8e6a9fb93e1a228cff4bde67244 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
|
note (non-blocking): idle children under the ACP-standard shape keep their route until the owner leaves.
|
|
note (non-blocking): the ACP-standard
|
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
2909109 to
3fcd601
Compare
issue (blocking): a cap-refused announcement still drew a card whose frames could never arrive.
|
|
note (non-blocking): ACP-standard children keep their route until the owner leaves.
|
|
note (non-blocking): item 5, the reader for the ACP-standard
|
3fcd601 to
0f1167f
Compare
0f1167f to
6709f6b
Compare
|
note (non-blocking): Backend Tests shard 5 failed on |
|
note (non-blocking): Backend Lint & Type Check fails on main code this PR does not touch. mypy reports |
|
note (non-blocking): item 6, the per-child redactor store duplicates
note (non-blocking): item 1,
|
|
HOLD for a maintainer at ec4f71b. This PR routes an announced Codex child's I found no defect. A child is learned only from the frame that announces it on a registered session, cannot be re-owned, is capped and released on a terminal state (runtime_frame_accounting.py#L186-L254), and between turns its permission request is still refused. The shared The item from our r125 review is met: Pearcekieser#54 tracks reading What clears the hold: a maintainer approves the child permission routing. Our earlier change request can then be dismissed. — crew-pr-reviewer (r135) |
buluoray
left a comment
There was a problem hiding this comment.
🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:
Approving at ec4f71b, including the maintainer decision the HOLD asked for: a Codex child announced on a registered session may send its session/request_permission to the owner approval pipeline while the owner turn is active (fail-closed between turns). Ownership rules hold: first announcement wins, a registered session is never taken as a child, ids are capped, routes are released on a terminal state or unregister.
Mutations run: removing the re-own guard (runtime_frame_accounting.py:237) reddens test_a_child_cannot_be_reowned_by_a_later_announcement; removing the codex gate (session_handle_updates.py:270) reddens test_lifecycle_frames_are_not_read_on_other_harnesses. Harness gates pass on the merged tree.
Please add before merge (spec, same PR):
docs/system-specs/modules/harness-parity.md:348(H16) and its Pinned by cell should name Codex andtest_codex_native_subagent_cards.py.docs/system-specs/modules/subagent.md:2780lists native subagents for kiro-cli, KAS and Claude only.
Follow-up: main is on codex-acp 2.3.0 (#25707). 2.3.0 accepts subagents: {} and sends the same frames and terminal states, but the fixtures are 2.2.3-preview.23 and 2.2.2 captures. A 2.3.0 capture would pin what users run. The PR body line "2.2.2 is current" is out of date.
|
Thanks @buluoray. Both spec additions are done locally and go out with the next push, as soon as a fork CI slot frees (queued now):
The PR body no longer calls 2.2.2 current; it says releases up to 2.2.2 drop the key and the pinned 2.3.0 accepts it. I renamed |
|
note (non-blocking): item 4, delete the legacy-row reader now that 2.3.0 is pinned.
note (non-blocking): item 5, the per-child redactor store duplicates
|
iamwhatever
left a comment
There was a problem hiding this comment.
Request changes at 7f8f941.
The code is unchanged since ec4f71b, the head r135 and @buluoray reviewed; this head adds the two spec lines @buluoray asked for (H16 in harness-parity.md and the native-subagent list in subagent.md) and renames one test. I found no defect. The announced-child route still requires a registered owner, stores only the first announcement, caps and length-checks ids, releases on a terminal state, and answers a child's permission request fail-closed between turns:
KiroCrew/src/kiro_crew/acp/runtime_reader_loop.py
Lines 196 to 246 in 7f8f941
One item needs a tracked issue: the 2.3.0 capture you said you would take after merge (comment of 2026-10-30). Main pins codex-acp 2.3.0, but the fixtures are 2.2.3-preview.23 and 2.2.2 captures, so nothing pins what users actually run. Please open an issue for it and link it in the description, as you did with Pearcekieser#54.
Separately, routing an announced child's session/request_permission to the owner's approval pipeline is a change to which requests reach approval, so it stays with a human maintainer. @buluoray's approval at ec4f71b covered that decision but was dismissed by the push; a maintainer re-approval on this head clears it, and our earlier change request can then be dismissed. CI is green and the branch merges cleanly.
— crew-pr-reviewer (r136)
|
todo (non-blocking): track the codex-acp 2.3.0 capture in an issue and link it in the description. Done. Pearcekieser/KiroCrew#65 covers capturing 2.3.0 (spawned, nested and cancelled child), sanitizing it like the existing fixtures, and replaying it through the card tests. If 2.3.0 turns out to send the ACP-standard note: the child permission routing still waits on a maintainer re-approval of this head. |
|
@Pearcekieser can you rebase onto main? It's conflicting again. Once it's clean I'll approve: I'm fine with the same call buluoray made at |
|
@tim-finnigan rebased onto current main as e97913e, no behaviour change. The only conflict was the "Instance fields written" docstring list in |
Security Scope Review (fork) — 🔴 BLOCK (blocking)Which legitimate operations does the review scope was never resolved: the generate job did not finish (it timed out, failed or was cancelled), so no leg ran; its log names the step that stopped No |
|
chore: fixes the Backend Ratchets & Boundaries failure on e97913e, no behaviour change. |
|
note (non-blocking): item 6,
|
|
note: Security Scope Review on 2fccd5f needs a maintainer rerun. It ends |
|
chore: rebased on main to clear the conflict with #28689, no behaviour change for existing routes. #28689 stamps the owner session's activity when a roster child sends a frame, so a working backend stays off the idle sweep. It added that line to the inline roster route, which this PR replaces with the shared @tim-finnigan this is the clean rebase. Security Scope Review on the previous head ended |
|
note (non-blocking): "The pinned 2.3.0 accepts it" has no 2.3.0 capture behind it.
note: Internal Content Scan on this head reports "NO VERDICT": its job failed at "Checkout base (trusted)", so no scan ran. The fork account cannot rerun it; a maintainer rerun should clear it. |
|
note (non-blocking): Backend Tests shard 5 on 45c7e17 failed two parametrizations of |
codex-acp gives a native subagent its own ACP session only for a client that declares clientCapabilities.subagents. The codex harness now declares it. The runtime routes a child's frames to the session that announced it, nested children included, and the session handle turns the subagent lifecycle updates (codex-acp 2.2.x subagent_spawned / subagent_state_update and the ACP-standard subagent_update) into the native card roster. codex-acp 2.2.2 and older are built on ACP SDK 1.x, which drops the declaration, so their "Start/Complete subagent" rows feed the same roster instead of rendering as generic tool calls.
|
HOLD for a maintainer at This head is a clean rebase of 45c7e17: the PR's own patch is identical. It still routes an announced Codex child's I found no defect. Since ec4f71b the only code changes are the constants move to AI findings judged non-blocking:
What clears the hold: a maintainer approves on this head. Our earlier change requests can then be dismissed. — crew-pr-reviewer (r146) |
bolichen97
left a comment
There was a problem hiding this comment.
Maintainer decision (security sign-off): accepted; loosening, not a tightening.
Approving at 9db45f4. On main, a Codex native child is neither registered nor announced, so its session/request_permission falls to the unannounced branch of the reader loop and is always answered with its least-destructive reject option, in a turn or between turns. With this PR, an announced child's request reaches the owner's approval pipeline while the owner has a turn in flight, the same pipeline a main-agent approval takes, and between turns it is still answered fail-closed (owner_no_active_turn), as before. So no request that is allowed today is newly refused. The shared _route_owned_child_frame keeps the existing roster child's behavior, and only a harness that declares clientCapabilities.subagents (Codex today) announces children. No regex is added. All checks pass.
|
@iamwhatever re-review ask at 9db45f4. Your r136 change request asked for two things, and both now look done:
CI is green and the branch merges cleanly. Your change request is the only thing still blocking. Could you re-review, and clear it if you agree? |
|
HOLD at 9db45f4 (policy: approval routing). This is the head our r146 HOLD reviewed, and I still found no defect. An announced Codex child's Why this stays with a human: it changes which requests reach approval. @bolichen97 gave that maintainer decision on this head on 2026-11-07, which is what r146 said would clear the hold. Our r136 change request on 7f8f941 is now the only thing keeping the PR at CHANGES_REQUESTED; both items it asked for are done (Pearcekieser#65 and #54 are linked), so it can be dismissed by a maintainer. All AI lanes pass and every check is green on this head. I read the source and CI; I did not run the tests. — crew-pr-reviewer (r149) |
Problem / Motivation
Goal: A native subagent that Codex starts in a Crew chat gets its own card in the Subagents panel, with its name, its lifecycle and its own output, the way a kiro-cli
use_subagentchild already does.In a Codex-backed chat, asking Codex to start a named native subagent produces two generic tool rows in the parent transcript ("Start subagent probe_worker", "Complete subagent probe_worker", saved as
kind=other). No card appears, and the child's output is attributed nowhere.Why it matters
The Subagents panel is the only place a chat shows a child's identity, progress and result. Codex users who delegate to native subagents see a parent that waits on something invisible, and they cannot tell a working child from a stuck or failed one.
Not a goal
subagent_updateshape, is upstream work (codex-acp#655).What changed (motivation → approach → change)
Symptom: no card, and generic tool rows instead.
Cause, from raw frames captured by driving codex-acp over stdio with the same synthetic prompt:
clientCapabilities.subagentsis declared.subagent_spawnedon the parent's session, ends it withsubagent_state_update, and streams the child's work under the child's own session id. Crew had no handler for either lifecycle frame. The runtime also dropped every frame for the child's id, because it only recognises children named by kiro-cli's ownerless_kiro.dev/subagent/list_updateroster.initializeschema drops unknownclientCapabilitieskeys, so the declaration never reaches those adapters and only the generic rows are sent. The pinned 2.3.0 accepts it.Change:
CodexHarness.client_capabilitiesreturnsCODEX_CLIENT_CAPABILITIES, the shared dict plussubagents: {}. JetBrains AIR's private opt-in is not sent, because it also turns on the rest of AIR's private contract._note_announced_child). That frame names its owner, so the child'ssession/updateandsession/request_permissionframes route to the announcing session even on a shared runtime. A nested child maps to the same root owner. The governance is the existing roster route's, now one shared method (_route_owned_child_frame). The map is capped atNATIVE_CHILD_ROSTER_CAP. An announcement the cap refuses is dropped before it reaches the handle, so no card is drawn for a child whose frames could not arrive, and the first refusal in an episode logs one warning. A terminal state releases the child's route, and the owner's children leave with it. The runtime learns announced children only for a harness whose handshake declaressubagents(today codex), and the handle's lifecycle intercept is gated on the codex backend._handle_announced_subagent) and emits it asEVENT_SUBAGENT_LIST, so_native_subagent_syncdraws the card unchanged. It reads codex-acp'ssubagent_spawned/subagent_state_updateshape only. The ACP-standardsubagent_updatethat codex-acp#655 proposes is not read until an adapter release sends it. The child's own frames already took the child-routed branch of_handle_update, which tags them as activity on the child's card and never as parent transcript. An announced child's text goes through its ownStreamRedactor, flushed before the closing state or byflush_native_child_texton a cut-short turn. Its name, task andagentPathare redacted before the cut and folding._handle_legacy_codex_subagentreads the "Start/Complete subagent" rows'rawInputinto the same roster instead of rendering them. Those adapters send no child output, so their cards carry identity and lifecycle only.docs/system-specs/modules/acp-client.mdgains a Codex row and the announced-child route.Files: the capability is in
src/kiro_crew/acp/types.pyandsrc/kiro_crew/acp/harness/codex.py; the route is insrc/kiro_crew/acp/runtime_frame_accounting.py,src/kiro_crew/acp/runtime_reader_loop.py,src/kiro_crew/acp/runtime_session_registry.pyandsrc/kiro_crew/acp/runtime_class.py; the roster is insrc/kiro_crew/acp/session_handle_native_children.py,src/kiro_crew/acp/session_handle_updates.py,src/kiro_crew/acp/session_handle_turn.pyandsrc/kiro_crew/acp/session_handle_class.py.Backwards compatibility
Compatible: kiro-cli, KAS, Claude and the other harnesses send the same capabilities and take the same routes as before; the roster route's governance moved into a method without changing behaviour. A codex-acp that ignores
subagentskeeps working, and its rows now feed a card.Removes nothing: the only rows no longer rendered are codex-acp's own "Start/Complete subagent" activity rows, which the card replaces.
Tests
test/test_codex_native_subagent_cards.py, 49 tests, driven from five reduced live captures intest/fixtures/codex_native_subagents/(codex-acp 2.2.3-preview.23 with the capability, and 2.2.2 with and without it). Session ids, call ids and the working directory are synthetic, and each file's_meta.notesays what was dropped.subagents: {}and nothing else changes. Other harnesses do not declare it.stateorsessionUpdateleaves the shared reader running, an announced child's frame keeps its owner off the idle sweep, unknown and between-turn frames are dropped, a child permission request reaches the owner during its turn and is answered fail-closed between turns, a finished child releases its route and a non-terminal state keeps it, unregistering forgets the owner's children, announcements past the cap are counted, not stored, and dropped with one warning per episode so no card is drawn, and another harness learns no announced children, while a backend with no runtime harness still has its own frames routed.prompt()path: the recorded child becomes one card with its own output and no parent tool row; a nested child names its parent and a follow-up gets a fresh card under its generation id; a cancelled child closes as cancelled; the roster resets per turn.subagent_spawn/subagent_donethrough_native_subagent_sync, and a child still open at turn end is closed by the turn.test_runtime_bindings.pyandtest_session_handle_bindings.pygain the six new bound members.Determinism: the module passed 5 repeats in file order and one run in a seeded shuffled order (seed 20261022, node ids collected by hook and shuffled), 38 of 38 each time, and 3 more repeats at 46 of 46 after the redaction and malformed-frame tests were added. The tests read no clock and do not sleep; the reader-loop tests wait on
_drainandawait_until.Proof: PROVEN test_a_credential_split_across_child_chunks_is_redacted, test_a_credential_the_label_cut_would_split_is_redacted_first, test_a_legacy_agent_path_is_redacted_before_it_becomes_a_name, test_held_child_text_reaches_its_card_before_the_turn_terminal, test_a_malformed_lifecycle_field_does_not_crash_the_shared_reader (head b3f200e)
Also run on current main with this PR's tests, the bindings, Claude card, native-subagent boundary, tool identity, harness parity, session provider, native card and crew-log guard modules: 3027 passed, 3 xfailed.
Manual verification
agent.acp_backend = codex, with codex-acp 2.2.3-preview.23. Sending the prompt above producedsubagent_spawn(Probe worker), eightsubagent_chunkframes carrying the child's text, andsubagent_donewitherror: nulland resultRunning the command now.probe-child-ok. The parent transcript showed only its own answer and thewaitcall. After a page reload the finished card was replayed.subagent_spawnedon the child's session), a follow-up announced as<id>:generation:2, and a cancelled child (subagent_state_updatecancelled). These are the committed fixtures.initializeand sends the same generic rows. Both captures are committed:legacy-rows-2.2.2.jsonlwithout the key andlegacy-rows-with-capability-2.2.2.jsonlwith it, the second keeping the reducedinitializeanswer.Screenshots / video
Why no screenshot: the diff changes no frontend code, so the card is the existing native card.
Pod evidence, live Codex run, finished card in the Subagents tab:
Related Issues
Fixes #23093
Related: #20034 (live card content for native children), codex-acp#655 (ACP-standard subagent sessions).
Follow-up: Pearcekieser/KiroCrew#54 tracks reading the ACP-standard
subagent_updateonce a codex-acp release ships #655, or gating thesubagentsdeclaration on the adapter version if that release lands first.Follow-up: Pearcekieser/KiroCrew#65 tracks a codex-acp 2.3.0 capture, the version main pins, replayed through the card tests.
Sibling sweep
Sibling: src/kiro_crew/acp/session_handle_native_children.py:275 -- changed here
Sibling: src/kiro_crew/acp/session_handle_native_children.py:360 -- changed here
Sibling: src/kiro_crew/acp/client_native_children.py:102 -- not affected -- the Claude roster drops a token the cut would split, and its cards redact the whole string
Sibling: src/kiro_crew/acp/session_handle_native_children.py:84 -- not affected -- kiro-cli's KAS roster labels predate this PR and are unchanged by it
Sibling: src/kiro_crew/acp/session_handle_updates.py -- changed here (the child text arm calls
_child_text_activity, which streams an announced child's text through its redactor; a kiro-cli child's text there is redacted per chunk, as on main)Sibling: src/kiro_crew/dashboard/chat_turn/native_cards.py -- changed here (
_native_flush_cut_shortdocstring: it now also reachesAcpSessionProvider.flush_native_child_text)Pattern harvest
Not generalizable: a harness capability that was never declared, plus a lifecycle frame shape only this adapter sends. The repo already has the guard for the general case, the "re-add the key in the same change that registers a handler" rule beside
ACP_CLIENT_CAPABILITIES, and this PR follows it.Checklist