Skip to content

fix(acp): show Codex native subagents as their own Subagents cards - #23094

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:fix/codex-native-subagent-cards
Nov 8, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:fix/codex-native-subagent-cards

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

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_subagent child 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

  • Richer live card content for native children, such as per-call tool rows and reasoning. fix(chat): show a native sub-agent's work live on its card #20034 covers that for every native child; this PR only feeds Codex children into the path it extends.
  • Any change to codex-acp. Adapter-side behaviour, including the ACP-standard subagent_update shape, is upstream work (codex-acp#655).
  • Per-child cancel or resume. A native child's recovery boundary stays its parent session.
  • Restoring native cards across a gateway restart. That limitation is the same for every harness.

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:

  1. The codex harness never asks for native subagent sessions. codex-acp gives a child its own ACP session only when clientCapabilities.subagents is declared.
  2. With the capability declared, codex-acp 2.2.3-preview.23 announces each child with subagent_spawned on the parent's session, ends it with subagent_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_update roster.
  3. codex-acp releases up to 2.2.2 are built on ACP SDK 1.9. That SDK's initialize schema drops unknown clientCapabilities keys, so the declaration never reaches those adapters and only the generic rows are sent. The pinned 2.3.0 accepts it.

Change:

  • CodexHarness.client_capabilities returns CODEX_CLIENT_CAPABILITIES, the shared dict plus subagents: {}. JetBrains AIR's private opt-in is not sent, because it also turns on the rest of AIR's private contract.
  • The runtime learns a child from the frame that announces it (_note_announced_child). That frame names its owner, so the child's session/update and session/request_permission frames 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 at NATIVE_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 declares subagents (today codex), and the handle's lifecycle intercept is gated on the codex backend.
  • The session handle turns lifecycle frames into the native card roster (_handle_announced_subagent) and emits it as EVENT_SUBAGENT_LIST, so _native_subagent_sync draws the card unchanged. It reads codex-acp's subagent_spawned / subagent_state_update shape only. The ACP-standard subagent_update that 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 own StreamRedactor, flushed before the closing state or by flush_native_child_text on a cut-short turn. Its name, task and agentPath are redacted before the cut and folding.
  • For SDK 1.x adapters, the codex-only _handle_legacy_codex_subagent reads the "Start/Complete subagent" rows' rawInput into the same roster instead of rendering them. Those adapters send no child output, so their cards carry identity and lifecycle only.
  • The native-subtask inventory in docs/system-specs/modules/acp-client.md gains a Codex row and the announced-child route.

Files: the capability is in src/kiro_crew/acp/types.py and src/kiro_crew/acp/harness/codex.py; the route is in src/kiro_crew/acp/runtime_frame_accounting.py, src/kiro_crew/acp/runtime_reader_loop.py, src/kiro_crew/acp/runtime_session_registry.py and src/kiro_crew/acp/runtime_class.py; the roster is in src/kiro_crew/acp/session_handle_native_children.py, src/kiro_crew/acp/session_handle_updates.py, src/kiro_crew/acp/session_handle_turn.py and src/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 subagents keeps 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 in test/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.note says what was dropped.

  • The codex harness declares subagents: {} and nothing else changes. Other harnesses do not declare it.
  • Through the real reader loop, a child's frames route to the announcing session beside a co-tenant, a nested child routes to the root owner, a child cannot be re-owned, a non-string state or sessionUpdate leaves 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.
  • Through the real 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.
  • The handle maps every 2.2.x terminal state, renders no card for a lifecycle shape it does not read, drops a state for an unannounced child, stops at the row cap, redacts a credential split across two child chunks or by the label cut or path folding, flushes held child text before every turn terminal, remembers a legacy row's call id only when it is bounded and its child got a row, and leaves lifecycle frames and legacy rows alone on other harnesses.
  • The roster drives subagent_spawn / subagent_done through _native_subagent_sync, and a child still open at turn end is closed by the turn.

test_runtime_bindings.py and test_session_handle_bindings.py gain 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 _drain and await_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

  • A throwaway pod of this branch on 127.0.0.1, agent.acp_backend = codex, with codex-acp 2.2.3-preview.23. Sending the prompt above produced subagent_spawn (Probe worker), eight subagent_chunk frames carrying the child's text, and subagent_done with error: null and result Running the command now.probe-child-ok. The parent transcript showed only its own answer and the wait call. After a page reload the finished card was replayed.
  • Driven over stdio against the same preview adapter: a nested child (subagent_spawned on the child's session), a follow-up announced as <id>:generation:2, and a cancelled child (subagent_state_update cancelled). These are the committed fixtures.
  • codex-acp 2.2.2 with and without the capability completes initialize and sends the same generic rows. Both captures are committed: legacy-rows-2.2.2.jsonl without the key and legacy-rows-with-capability-2.2.2.jsonl with it, the second keeping the reduced initialize answer.

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:

A live Codex native subagent, Probe worker, shown as its own completed 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_update once a codex-acp release ships #655, or gating the subagents declaration 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_short docstring: it now also reaches AcpSessionProvider.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

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

@Pearcekieser
Pearcekieser requested review from a team and KiroCrewCaptain as code owners October 22, 2026 13:18
@Pearcekieser
Pearcekieser requested a review from buluoray October 22, 2026 13:18
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 22, 2026
@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 9db45f4998f8298acaa7ce103b7aec795b1641f8 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 Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns: the new route is limited to harnesses that declare subagents in their handshake, it reuses the existing roster's routing rules, and every other harness takes the same path as before.

Notes

  • The runtime turns the route on when the harness declares subagents, but the session handle turns its intercept on when the backend is codex. Today these pick out the same harness. If another harness later declares subagents, the runtime will route its child frames while the handle still renders them as raw lifecycle frames. Gating both on the same capability would keep them in step.

[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 .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 Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

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

Premise-level review of 9db45f4998f8298acaa7ce103b7aec795b1641f8 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 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

  • Item 6 — inherited: the description says "The pinned 2.3.0 accepts it", so _handle_legacy_codex_subagent only helps people running a codex-acp older than the pin. I found no version pin in src/kiro_crew (searched codex-acp@, CODEX_ACP_VERSION, 2\.3\.0 under acp/harness: 0 pins), so I can't tell whether anyone still runs one of those versions. Subtraction: delete _handle_legacy_codex_subagent, _legacy_subagent_tool_ids, _LEGACY_ACTIVITY_STATUS and the second codex gate in _handle_update, unless a supported install on an SDK 1.x adapter is named.

What this change ships

Inventory (8 items) — 7 justified

Intent: a Codex user who delegates to a native subagent sees that child as its own Subagents card, with identity, lifecycle and output. FIX.

  1. Codex sessions now declare clientCapabilities.subagents, so codex-acp gives each child its own session — justified
  2. A Codex native child appears as a card in the Subagents panel, with its name, state and output — justified
  3. A child's updates and permission requests reach the session that announced it, even when other sessions share the runtime — justified
  4. The announced-child route map is capped: past the cap the announcement is dropped (so no card is drawn) and one warning is logged — justified
  5. A child's route is released on a terminal state, and when its owner unregisters — justified
  6. On older adapters, the "Start/Complete subagent" tool rows become cards instead of transcript rows — inherited, serves only pre-pin adapters
  7. A child's text is redacted per stream and flushed before the card closes or when a turn is cut short — justified
  8. The roster route's child-frame handling is moved into the shared _route_owned_child_frame — justified

[FIRST-PRINCIPLES-REVIEWED] 9db45f4

Description read

[DESCRIPTION-READ] 9f03f63cafe4fb5660f07381818d87c251b9c8e6a9fb93e1a228cff4bde67244

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 Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 9db45f4

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): idle children under the ACP-standard shape keep their route until the owner leaves.

rebutted: this is deliberate and bounded. The standard shape keeps one child id across delegations, so an idle child can run again under the same id, and dropping its route on idle would drop that child's next run. The map is capped at NATIVE_CHILD_ROSTER_CAP (4096) per runtime, refusals are counted in _announced_overflow, and unregister_session removes every child of the departing owner. Filling the map needs 4096 distinct children inside one session's lifetime.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): the ACP-standard subagent_update parser and the separate _announced_subagent_roster.

rebutted, item 5: the standard shape is the one codex-acp#655 sends to clients that declare subagents, which this PR makes Crew do. Without the branch, cards would disappear again on that release with no error. It is about 40 lines, and test_acp_standard_subagent_update covers each state, built from #655's own v1 fixtures.
rebutted, item 7: _kas_subagent_roster is filled only by _handle_kas_subagent, which is gated on ACP_BACKEND_KAS. Sharing the dict would save one field and one clear(), but the KAS code and its docs would then describe a store that codex writes too. Two fields keep each harness's roster readable on its own, at the cost of one line in the per-turn reset.

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 9db45f4

@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 Oct 22, 2026
@Pearcekieser
Pearcekieser force-pushed the fix/codex-native-subagent-cards branch from 2909109 to 3fcd601 Compare October 22, 2026 13:57
@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=d547b9aab6df fixed: a cap-refused announcement no longer draws a card

issue (blocking): a cap-refused announcement still drew a card whose frames could never arrive.

fixed in 3fcd601. _note_announced_child returns False when NATIVE_CHILD_ROSTER_CAP refuses an announcement, and _reader_loop then drops that frame through _note_dropped_frame, so the handle never sees it and draws no card. The child's later frames stay unroutable as before: updates are dropped and permission requests are answered fail-closed under roster_overflow_auto_reject.
The first refusal of an episode logs one WARNING naming the cap and the owner. The episode ends when the map empties on unregister_session, which resets _announced_overflow and re-arms the warning.
Pinned by test_a_refused_announcement_draws_no_card_and_warns_once: two refused children leave the owner's queue empty and log exactly one warning.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): ACP-standard children keep their route until the owner leaves.

rebutted, same as on 2909109: the standard shape reuses one child id across delegations, so releasing on idle would drop that child's next run. The map holds 4096 ids per runtime, unregister_session clears the owner's children, and since 3fcd601 a refused announcement draws no card and logs one warning, so a full map shows up in the log instead of as dead cards. Releasing on a finished idle belongs with the adapter release that settles the standard state shape.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): item 5, the reader for the ACP-standard subagent_update.

rebutted, same as on 2909109: codex-acp#655 sends this shape to every client that declares subagents, and this PR is what makes Crew declare it. Without the reader, Codex cards would disappear again on that release with no error. "Not a goal" excludes changing codex-acp, not reading a shape it is about to send. The reader is about 40 lines, and test_acp_standard_subagent_update covers each state from #655's own v1 fixtures.

@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 Oct 22, 2026
@Pearcekieser
Pearcekieser force-pushed the fix/codex-native-subagent-cards branch from 3fcd601 to 0f1167f Compare October 22, 2026 15:09
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 22, 2026
@Pearcekieser
Pearcekieser force-pushed the fix/codex-native-subagent-cards branch from 0f1167f to 6709f6b Compare October 22, 2026 15:57
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): Backend Tests shard 5 failed on test_host_git_repo_exec_neutralization.py::TestDashboardFileDiff::test_fixed_key_programs_and_hooks_do_not_run, which arrived on main today with #24822. It failed its own precondition, not the code under test: fixture is inert: bare git -c core.fsmonitor= status --porcelain ran no marker, so the runner's git never ran the planted hook. This PR touches no git or file-diff code, and the test passes 3 of 3 times locally on head b3f200e. The fork account cannot rerun the job; a maintainer rerun of shard 5 should clear it.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

chore: rebased on current main to pick up #25469, no behaviour change. #25469 fixes test_fixed_key_programs_and_hooks_do_not_run, the test behind the shard 5 failure on b3f200e. On head 366a3e7 that test passes, and the related suites pass: 3379 passed, 2 xfailed.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): Backend Lint & Type Check fails on main code this PR does not touch. mypy reports session_create has no attribute _frame_parents at slack/gateway_runtime/turn_approvals.py:404 and dashboard/chat_api/chat_send.py:318. Main moved _frame_parents to crew_filing in #25669, and #25706 is the open fix for those two imports. This PR will rebase onto main once #25706 lands.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

chore: rebased on current main to pick up #25706, no behaviour change. #25706 fixes the two _frame_parents imports behind the Backend Lint & Type Check failure on 366a3e7. Head 5e523b8 has the same diff; the related suites pass, 3336 passed, 2 xfailed.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): item 6, the per-child redactor store duplicates client_turn._redact_native_child_events.

rebutted: the shared part is already shared. Both paths use kiro_crew.security.StreamRedactor, which holds all the redaction logic. What each side keeps is a dict of redactors keyed by child id and a loop that flushes it, about 15 lines. The two stores live on different objects with different lifetimes and flush points: AcpClient keeps a Claude child's redactor across turns, because a background Claude child keeps running into the next turn, while the session handle drops codex's at every turn terminal, because codex announces a continued child under a new generation id. A shared helper would need both policies as parameters and would tie the runtime handle to AcpClient's internals for 15 lines.

note (non-blocking): item 1, fix versus feat.

rebutted: #23093 reports a defect in a shipped path. Codex children already ran inside Crew chats, but the runtime dropped every frame on the child's session id and their work showed as generic "Start subagent" tool rows. Crew already shows native children as cards for kiro-cli and Claude, so the PR repairs a missing case of an existing feature.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

chore: no-change push. ec4f71b has the same tree as 5e523b8; it only reruns Opus 5.5 Review, which ended "review incomplete" on 5e523b8. The fork account cannot rerun jobs, and a description edit does not rerun that lane.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD for a maintainer at ec4f71b.

This PR routes an announced Codex child's session/request_permission frames to the owner session's approval pipeline (runtime_reader_loop.py#L196-L246). Before, those requests got the fail-closed auto-answer. A change to which requests reach approval is reserved for human review.

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 _route_owned_child_frame keeps the old roster route's behaviour. Every earlier blocking finding has a fix and a regression test, all lanes are clear on this head, and CI is green.

The item from our r125 review is met: Pearcekieser#54 tracks reading subagent_update once codex-acp#655 ships. It lives on your fork; moving it to this repository would make it visible to maintainers.

What clears the hold: a maintainer approves the child permission routing. Our earlier change request can then be dismissed.

— crew-pr-reviewer (r135)

buluoray
buluoray previously approved these changes Oct 29, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🤖 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 and test_codex_native_subagent_cards.py.
  • docs/system-specs/modules/subagent.md:2780 lists 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.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

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):

  • harness-parity.md H16: a "Codex yes once declared" sentence (the declaration, the announced-child route with its cap and release, the SDK 1.x legacy rows), and the Pinned by cell now names test_codex_native_subagent_cards.py.
  • subagent.md: the native-subagent list names Codex on the codex harness.

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 test_the_pinned_adapter_accepts_the_declaration_and_keeps_its_rows to test_an_sdk1_adapter_accepts_the_declaration_and_keeps_its_rows, since 2.2.2 is no longer the pin. The push also rebases onto current main (no conflicts; 2633 related tests pass, 2 xfailed). I will take the 2.3.0 capture as a follow-up after merge.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): item 4, delete the legacy-row reader now that 2.3.0 is pinned.

rebutted: the 2.3.0 pin is the version test/real_adapters runs, not the version a Crew user has installed. A user with codex-acp 2.2.2 or older today sees each native child as a pair of generic "Start/Complete subagent" tool rows; the reader turns those into the same card, with name and lifecycle. Deleting it would leave those users with no card, which is the defect #23093 reports. It is about 40 lines, codex-gated, and its fixtures are live captures.

note (non-blocking): item 5, the per-child redactor store duplicates AcpClient's.

rebutted, as on 5e523b8: the redaction itself is the shared StreamRedactor; what each side owns is a dict and a flush loop, and the two flush on different lifetimes (Claude keeps a child's redactor across turns, codex drops it at every turn terminal).

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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:

async def _route_owned_child_frame(
self: AcpRuntime, msg: JsonRpcMessage, session_id: str, owner: str
) -> None:
"""Deliver one backend-child frame to the registered session that owns it.
The two child routes share this governance: the ownerless roster's child on a
single-session runtime, and a child announced on its owner's own session.
A permission REQUEST is routed only while the owner has an in-flight prompt
(an outstanding routed request = the dispatch loop is consuming the queue).
Between turns nothing reads the queue until the next prompt's drain, so a
background child's request would sit unanswered -- the original hang with
extra steps. It is answered fail-closed NOW instead.
"""
_owner_turn_active = owner in self._turn_active_sessions
if msg.id is not None and msg.is_method(METHOD_REQUEST_PERMISSION) and not _owner_turn_active:
await self._spawn_answer_task(
msg,
session_id,
# Registered + announced — the owner just has no in-flight prompt.
# A distinct SEL tag keeps normal background-child behavior
# distinguishable from a real misconfiguration in the audit trail.
reason="owner_no_active_turn",
)
# Yield so spawned answer tasks actually RUN between frames: with 129+
# frames already buffered, readline() returns without suspending, and
# the reader would hit the flood cap before any answer task had a
# chance to complete — falsely killing a responsive runtime. One
# loop-tick lets quick answers drain; a genuinely wedged backend still
# accumulates blocked tasks and trips the cap.
await asyncio.sleep(0)
elif not _owner_turn_active:
# An UPDATE between the owner's turns (either session/update spelling).
# Nothing reads the queue until the next prompt's dispatch loop, and
# _run_turn clears the per-toolCallId caches at turn start and then
# discards stale non-permission frames from the queue — so a
# between-turns update can never contribute a cache write or an activity
# event. Queueing it would only grow an unbounded queue in gateway memory
# while the slot idles (session queues have no depth cap). Unlike a
# REQUEST there is no protocol obligation to answer, so take the
# counted-drop path.
self._note_dropped_frame(session_id, msg.method)
else:
# Hang-resilience series: a child permission request delivered to the
# mode-parity pipeline. Counted so routed requests are observable next to
# the dropped-frame counter — a permission request that is neither routed
# nor answered leaves its crew waiting on a prompt nobody can see.
if msg.id is not None and msg.is_method(METHOD_REQUEST_PERMISSION):
emit_counter(CHILD_PERMISSION_ROUTED, {"surface": "runtime"})
await self._session_queues[owner].put(msg)

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)

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

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 subagent_update, that part lands in #54. The description links #65 under Related Issues. Only the description changed, so the head is still 7f8f941.

note: the child permission routing still waits on a maintainer re-approval of this head.

@tim-finnigan

Copy link
Copy Markdown
Contributor

@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 ec4f71b, an announced Codex child's session/request_permission going to the owner's approval pipeline during the owner's turn and fail-closed between turns. The code hasn't changed since that approval, so I don't need anything else.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

@tim-finnigan rebased onto current main as e97913e, no behaviour change. The only conflict was the "Instance fields written" docstring list in acp/session_handle_turn.py: main added _mcp_sign_in_ask and _mcp_sign_in_asked, this PR adds its native-child fields, and the list now has both. The related suites pass (3339) and the branch merges cleanly. Ready for your approval.

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Security Scope Review (fork) — 🔴 BLOCK (blocking)

Which legitimate operations does e97913e261b637cc4e30a1a6759a1f06592bbabd newly refuse? Model proposes, scripts/deny_diff.py decides — updated in place on each push. A script-confirmed regression blocks PR readiness.

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 [SCOPE-REVIEWED] marker for this head was produced, so the model's text is withheld: it cannot be shown to describe this revision. See the job logs.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

chore: fixes the Backend Ratchets & Boundaries failure on e97913e, no behaviour change. acp/types.py reached 2,025 lines against the 2,000-line cap: main has it at exactly 2,000 and this PR added 25. Head 2fccd5f moves those definitions (CODEX_CLIENT_CAPABILITIES, the two lifecycle update names and the terminal states) into a new acp/codex_subagent_wire.py, next to kas_wire.py; types.py is now identical to main, and the callers and the test import from the new module. The line-cap check passes with no failures, and the related suites and the fast-gate ratchet files pass. The same push rebases onto current main and reruns Security Scope Review, whose generate job did not finish, and shard 3, where test_skill_catalog_snapshot (not touched here) failed once and passes 3 of 3 locally.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): item 6, AcpSessionProvider.flush_native_child_text probes its handle with getattr although AcpSessionHandle always binds the method.

acknowledged, not changed in this PR: the probe matches the provider's neighbouring delegates (child_fidelity_aware, accepts_elicitation and kas_projected_agent all read the handle through getattr), and the dashboard caller _native_flush_cut_short already treats a missing method as nothing held. A direct call is a one-line change with no behaviour difference; I would rather not restart the review round on this head for it.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note: Security Scope Review on 2fccd5f needs a maintainer rerun. It ends [scope-floor:unsettled]: the candidates job succeeded, then validation and adjudication were skipped, so no leg ran and no scope result exists for this head. PR Readiness now waits only on it; every other check is green. The same thing happened on e97913e. The check passed on ec4f71b and 7f8f941, and the only code change since then moves the codex constants out of acp/types.py into acp/codex_subagent_wire.py for the line cap. The fork account cannot rerun the job. @tim-finnigan, the head is rebased and clean as you asked; a rerun of that one check plus your approval should clear it.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

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 _route_owned_child_frame. Head 45c7e17 puts the stamp at the top of _route_owned_child_frame, so the roster child keeps the behaviour from main and an announced Codex child gets it too. test_an_announced_childs_frame_counts_as_its_owners_activity (owner turn active and not) fails without the stamp. The registry docstring lists both sides' fields. 2504 related tests pass, including test_idle_sweep_backend_activity.py.

@tim-finnigan this is the clean rebase. Security Scope Review on the previous head ended [scope-floor:unsettled] with no leg run; this push reruns it.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): "The pinned 2.3.0 accepts it" has no 2.3.0 capture behind it.

acknowledged: the claim comes from @buluoray's check against 2.3.0 in the approval at ec4f71b ("2.3.0 accepts subagents: {} and sends the same frames and terminal states"), not from a committed fixture. Pinning it with a 2.3.0 capture is Pearcekieser/KiroCrew#65, which the description links. No code depends on the version: the handle reads whichever of the two shapes arrives.

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.

@Pearcekieser

Pearcekieser commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor Author

note (non-blocking): Backend Tests shard 5 on 45c7e17 failed two parametrizations of test_decisions_end_to_end.py::test_jev_response_reaches_the_assembled_message (assert 0 == 1, an empty list). This is the known main-side flake #29457 ("gets no judge request since #26950"), with fixes open in #29458 and #29623. Locally it fails 3 of its 5 parametrizations both on this head and on bare main 89c6361, so it does not come from this PR, which touches nothing in decisions or message assembly. (An earlier version of this comment said it passed locally; that was wrong.) Together with the Internal Content Scan checkout failure, a maintainer rerun of shard 5 and the scan, or a rebase once #29458 or #29623 lands, should leave the round green.

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.
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD for a maintainer at 9db45f4998f8298acaa7ce103b7aec795b1641f8 (policy: approval routing).

This head is a clean rebase of 45c7e17: the PR's own patch is identical. It still routes an announced Codex child's session/request_permission to the owner's approval pipeline during the owner's turn and answers it fail-closed between turns (runtime_reader_loop.py#L196-L246). A change to which requests reach approval stays with a maintainer. @buluoray approved this at ec4f71b, but that approval was dismissed, and @tim-finnigan's offer to approve once the branch is clean has not been acted on yet.

I found no defect. Since ec4f71b the only code changes are the constants move to acp/codex_subagent_wire.py and the owner-activity stamp from #28689. The item in our r136 change request is done: Pearcekieser#65 tracks the codex-acp 2.3.0 capture, and #54 tracks subagent_update. Both are linked in the description. All current-head lanes pass, and Security Scope reports nothing to scope; the BLOCK comment on the PR is from e97913e. CI is green and the branch merges cleanly.

AI findings judged non-blocking:

  • Design: runtime and handle gate on different signals. Only codex declares subagents today, and a mismatch would show raw rows instead of misrouting; r124 accepted the reply.
  • First Principles: the SDK 1.x legacy-row reader could be removed. This is an optional subtraction.

What clears the hold: a maintainer approves on this head. Our earlier change requests can then be dismissed.

— crew-pr-reviewer (r146)

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

@bolichen97

Copy link
Copy Markdown
Contributor

@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?

@iamwhatever

Copy link
Copy Markdown
Contributor

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 session/request_permission reaches the owner's approval pipeline only while the owner has a turn in flight, and is answered fail-closed between turns (runtime_reader_loop.py#L196-L249). Only a registered session can own a child, the first announcement wins, and ids are capped and length-checked (runtime_frame_accounting.py#L188-L256).

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)

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)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Codex native subagents do not appear as Subagents cards

5 participants